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PREFACE 


MANUAL OBJECTIVES 


The DECnet-VAX User's Guide describes VAX/VMS network operations’ such 
as remote file access and task-to-task communication. The manual is 
divided according to the types of operations you can perform and _ the 
level at which you access the network. In particular, this manual 
describes the DIGITAL Command Language (DCL) commands you can use _ to 
manipulate remote files and for network command terminal use. It also 
describes all the information necessary to program remote file access 
and task-to-task communication applications. 
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INTENDED AUDIENCE 


This manual provides information needed by VAX/VMS users who want to 
perform network operations. Interactive and batch users should be 
familiar with DCL, which the VAX/VMS Command Language User's Guide 
describes in detail. Programmers should use the information in this 
manual aS a supplement to the reference manualS and user guides 
provided for higher-level languages, and to the manuals that explain 
VAX-11 Record Management Services (RMS) and VAX/VMS System Services. 


STRUCTURE OF THIS DOCUMENT 


The DECnet-VAX User's Guide consists of seven chapters, four 
appendixes, and a glossary, which are described below: 


e Chapter 1 briefly describes the wayS you can access’ the 
network and the types of network operations you can perform. 
A general network topology, which serves aS a common reference 
for all examples, is also included. 


e Chapter 2 describes general concepts that pertain to accessing 
the network at the command level and through user programs. 


e Chapter 3 presents the DCL commands that you can use_ for 
network operations. 


e Chapter 4 presents the VAX-11 RMS calls and_ procedures - that 
you can use to access files on remote nodes. 


@e Chapter 5 describes the concepts’ central to DECnet-VAX 
task-to-task communication and the use of higher-level 
languages for such communication. 


e Chapter 6 summarizes the procedures for transparent 
task-to-task communication using system services. 


ix. 
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e Chapter 7 summarizes the _ procedures for nontransparent 
task-to-task communication using system services. 


e Appendix A provides a table of object type code values and 
their descriptions. 


e Appendix B provides a complete table of RMS control block 
fields and any related qualifications governing their use for 
network operations. 


e Appendix C summarizes system service error messages associated 
with network-related functions. 


e Appendix D summarizes mailbox messages and their meanings’ for 
nontransparent communication. 


e The Glossary defines terms used in this manual. 


ASSOCIATED DOCUMENTS 


For information concerning DECnet-VAX system management, refer to’ the 
DECnet-VAX System Manager's Guide and the DECnet-VAX Network 
Installation manual. The DECnet-VAX Cross-System Notes describe the 
use of DECnet-VAX in a heterogeneous network environment. The VAX/VMS 
Release Notes describe any constraints on using DECnet-VAX with the 
current version of VAX/VMS. The VAX-11 Information Directory and 
Index provides information on the entire VAX/VMS document set. The 
directory briefly describes all the documents in the set and explains 


the intended audience for each one. For general backg round 
information about the VAX/VMS system, refer to the VAX/VMS Primer and 
the VAX/VMS Summary Description and Glossary. Finally, the 





Introduction to DECnet manual serves as a companion to the DECnet-VAX 
documentation set. This manual provides a general overview of DECnet 
software from a perspective independent of individual DECnet 
implementations. 


Because the user guides for the higher-level languages available under 
VAX/VMS contain information relating to remote file access and 
task-to-task communication, you should refer to them for applications 
in these areas. 


The following functional specifications define DIGITAL Network 


Architecture (DNA) protocols to which all implementations of DECnet 
adhere: 


_—_— 


DIGITAL Data Communications Message Protocol Functional 
Specification 


rr nt 


Network Management Functional Specification 


Graphic Conventions 
character 


(or chars) 


$ COPY 


S$ FROM: *.* 
S TO: TRNTO: :*.* 


$DASSGN_S_ chan 


SASSIGN S devnam,chan[,acmode] 


"foreign-—file-spec-string" 


"task-spec-string" 


$ TYPE BOSTON: : TEXT.COM 


es 
e 


(or) 


DELETE file-spec,... 


PREFACE 


The term characters refers to the 
set of alphanumerics that includes A 
through Z, 0 through 9, _, and §$. 

Command show all output 
characters that 
displays in 


examples 
lines or prompting 
the system prints or 
black letters. 


This document uses red lettering to 
indicate all user-entered information 


and to show user-supplied call 
instruction parameters. 
All calls and command example verbs 


are shown in a call or command line 
in capital letters, and they must be 
entered as shown. Arguments are 
shown in a call as lowercase letters. 
You substitute the argument shown in 


the call format with the precise 
information requested. 

Square brackets enclose optional 
keywords and arguments. Do not 
include the brackets when entering 


the command. 


arguments within braces 
must choose only 

arguments. 
braces when 


Keywords or 
indicate that you 
one of the keywords or 
(Do not include the 
entering the command.) 


The use of ellipses means that not 
all of the information that the 
system would display in response to 
the particular command is shown, or, 
that not all the information a user 
would enter is shown. 


xi 


CHAPTER 1 


DECNET-VAX OVERVIEW 


DECnet is the collective name for a set of software and hardware 
products that allow DIGITAL operating systems to participate in a 
cooperative environment known as a. network. DECnet-VAX is’ the 
software package that extends the basic capabilities of the VAX/VMS 
operating system on a VAX-11 computer. Beyond the normal VAX/VMS 
capabilities, DECnet-VAX provides a layered structure of protocols for 
network operations. These protocols allow you to use the resources on 
remote DIGITAL computers, even though these systems may run under an 
operating system other than VAX/VMS. This manual describes’ the 
DECnet-VAX facilities for accessing and using these resources. 


This chapter describes the DECnet-VAX user interface to the network in 
terms of a hypothetical network topology. Of course, each network 
will be tailored to the individual needs of its users and_ the 
resources available. The network topology presented in this chapter 
serves aS a common reference for the user examples presented in this 
manual and highlights the operational capability of DECnet-VAX within 
a heterogeneous network environment. In this manual, however, only 
the DECnet-VAX perspective on network operations is presented. For an 
overview of DECnet, refer to the Introduction to DECnet manual. 


1.1 VAX/VMS USER INTERFACE TO THE NETWORK 


The VAX/VMS operating system and DECnet-VAX communications’ software 
are integrated to provide a high degree of transparency for user 
operations. When developing network applications, you can use 
standard DCL commands, higher-level language I/O statements, VAX-11l 
RMS service calls, and system service calls to perform network 
operations. For some applications, however, it is desirable (and 
sometimes necessary) to have more direct access to network-specific 
information and operations. For this purpose, DECnet-VAX provides 
nontransparent communication. The following sections describe general 
transparent and nontransparent features of DECnet-VAX in terms of the 
user interface to the network. 


1.1.1 DECnet-VAX Network Operations 


DECnet-VAX supports a variety of network operations that employ 
VAX/VMS programming languages. In addition to VAX-11 MACRO, you can 
use most of the higher-level languages such as VAX-11 FORTRAN, VAX-11 
BASIC, VAX-11 BLISS, VAX-11 PASCAL, VAX-11 PL/I, and VAX-11 COBOL to 
develop networking applications. With any of these languages, you can 
access remote files and create tasks that exchange information across 
the network. You can also usSe DIGITAL Command Language (DCL) commands 
to create and access remote files and to perform many file management 
functions on other nodes. 


Note that throughout the manual, the term task refers to an image 
running in the context of a process, the term local refers to the node 
at which you are located physically, and the term remote refers to any 
node on the network other than the one at which you are located. 


Table 1-1 summarizes the normal use of the programming languages’ for 
specific network operations that you can perform with DECnet-VAX. 


Table 1-1: Network Access Levels 


User Language Network Operation Language Calls 


Network command 
terminals 





DCL commands Transparent 
network access 


via DCL 
















Remote file 
manipulation 







Task-to-task 
communication 






















Remote file access 
(files and records) 


Higher-level 
languages 


Higher-level 
language 
I/O statements 





Task-to-task 
communication 









Transparent 
network access 
via RMS 















MACRO or 
higher-level 
languages 


RMS service 
calls 


Remote file access 
(files and records) 









Task-to-task 
communication 





















MACRO or 
higher-level 
languages 


Task-to-task 
communication 


System service 
calls 


Transparent and 
nontransparent 
network access 
via QIO 








The way you access the network is directly related to the language you 
use and the network operation you perform. For example, you may want 
to use standard VAX-11 RMS calls in a VAX-11 MACRO program to access 
remote files, then use system service calls to communicate between 
MACRO programs in a task-to-task communication application. Figure 
1-1 shows three access levels and the corresponding network 
operations. The various levels of network access provide a convenient 
context in which to discuss typical user operations over the network. 


Network User Interface | Network Access Level 









TT TE TE OE NTE 
Oo 5s FY | DCL Interpreter DCL 
RMS-usi Access 
DCL Commands | & vide 
Images Level 
Remote 
File Access 
Programs 
RMS 
Access 
Level 
Transparent 
Task-to-Task 
Programs 
Transparent System 
Task-to-Task Service 
Programs Access — 
Level 
Nontransparent DECnet-VAX 
Task-to-Task Software 
Programs 
Communications 
| Device 
| ZK-833-82 


Figure 1-1: Network Access Levels and DECnet-VAX User Interface 


The first two levels of access, DCL and RMS, are entirely transparent 
to the network user. BecauSe you use standard DCL commands and RMS 
service calls to access remote files, no DECnet-specific calls are 
required at these levels of access. You need only specify the remote 
node on which the file resides in your file specification. Likewise, 
higher-level language tasks can use a variation of the standard 
VAX/VMS file specification in conjunction with standard I/O statements 
to access remote tasks and exchange information; thus, this form of 
task-to-task communication is also transparent. As with 
device-independent input/output (I/0) operations, transparent network 
access allows you to move data across the network with little concern 
for the way this operation is performed. 


The third level of access, system services, provides both a 
transparent and a nontransparent user interface to the network. 
Transparent communication at the system service level provides all the 


basic functions necessary for two tasks to exchange messages over’ the 
network. As with the higher-level language I/O interface, these 
operations are transparent because they do not require DECnet-specific 
calls. Rather, you use standard system service calls to implement 
them. Nontransparent communication extends this basic functionality 
to allow a nontransparent task to receive multiple inbound connections 
and to use additional network protocol features such as optional user 
data and interrupt messages. As with device-dependent I/0, 
nontransparent communication allows you to exploit certain 
network-specific characteristics to coordinate a more controlled 
communication environment for exchanging information. 


1.1.2 A Network Topology 


To highlight the operational capabilities of DECnet-VAX, this section 
presents a hypothetical network example comprised of various DIGITAL 
operating systems. Figure 1-2 illustrates a network topology (or 
geometry) which includes several VAX/VMS systems. No two networks are 
likely to have the same distribution of resources or the same 
topology; therefore, this example serves only to illustrate the use 
of DECnet-VAX functions in a heterogeneous network environment. The 
examples throughout this manual refer back to the network topology 
presented here, 
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Figure 1-2: Network Topology and Related Functions 


The computer network in Figure 1-2 has a centralized VAX/VMS host 
processor (BOSTON) and remote distributed systems dedicated to 
particular functions. For the purpose of discussion, this network 
represents a corporate division that oversees such functions as 
research and development, process control, and order entry. In this 
example, the size and functions of the network are simplified. 


The VAX/VMS host processor at node BOSTON performs major computation, 
controls the central data base, and supervises the general operation 
of the network for the division. The remote computers (nodes) perform 
various network-related functions in concert with the host processor. 
The VAX/VMS computers at nodes TRNTO and DENVER represent corporate 
computing facilities, where the corporation generates reports, 
production schedules, and inventory and cost accounting procedures. 
The host computer provides information to these facilities to account 
for divisional productivity. 


Figure 1-3 indicates the type of typical DECnet-VAX operations that 
enable the host to serve this role. Nodes NYC and BANGOR are 
satellite computers involved with instrumentation and process control. 
The host coordinates the manufacturing process via down-line system 
and task loading and transparent task-to-task communication for data 
acquisition and retrieval. (Refer to the DECnet-VAX System Manager's 
Guide for more information on down-line loading.) 


Node DALLAS provides computing power sufficient for conducting 
experiments and collecting data; research and development involving 
development of local programs replaces the need to use the resources 
of the host. The host, however, has access to this remote data base, 
and controls simple procedures that tasks at both NYC and DALLAS must 
carry out in concert. A nontransparent task running on the host 
processor controls the exchange of information between the two tasks. 


Finally, marketing has direct input to the host in the form of order 
entry at node KANSAS. Typically, such input might involve direct 
access to files or programs that update the central data base. The 
host, in turn, updates the remote data base with inventory information 
and other sales-related data. 
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Figure 1-3: Operational Capabilities of DECnet-VAX 


Such a network takes advantage of the host's resources efficiently and 
effectively. The centralized location of the host computer enables it 
to communicate with all remote nodes performing their individual 
functions. To control and monitor the various functions of the 
division, the local VAX/VMS user in interactive or batch mode can use 
DCL commands to access remote files and devices; the network 
programmer can develop programs for controlling the manufacturing 
Process and for accesSing files on the remote data bases. Remote 
command terminals allow network users to log in at remote VAX/VMS 
nodes and perform operations just as they would at the local node. 
Thus DECnet-VAX provides all the facilities for operating within a 
network environment while distributing the processing load efficiently 
among the available network resources. 


CHAPTER 2 


ACCESSING THE NETWORK 


This chapter presents general information that you need to access’ the 
network via DECnet-VAX software. This information includes’- the 
general format for network file and task specifications, access 
control parameters, the use of logical names, and the use of network 
command terminals. The format for file specifications is applicable 
to file handling operations for both the DCL and the RMS interfaces to 
the network. The task specification format pertains to task-to-task 
communication. The information on access control is significant 
because it defines the way that both local and remote nodes grant 
access to their system resources. Finally, this chapter discusses the 
use of logical names, focusing on the flexibility that they provide. 


2.1 FILE AND TASK SPECIFICATIONS 


DECnet-VAX uses the standard VAX/VMS file specification format for 
remote file handling and task-to-task communication applications. A 
node specification string that includes a node name with an optional 
access control string must be present. You use the optional access 
control string to explicitly specify access information for both files 
and tasks at the remote node (see Section 2.2). Task-to-task 
communication requires the use of a task specification string enclosed 
in quotation marks. This string identifies the target task to which 
you want to connect on a remote node. 


Network file specification strings are composed of eight major fields 
(or elements), which are arranged in the following formats: 


device: [directory] filename.type;version 
node-spec:: "foreign-file-spec-string" 
"task-spec-string" 


The punctuation marks and brackets included in these formats are 
required to separate the fields of the file specification. The double 
colon (::) after node is treated as a single delimiter. Angle 
brackets (<>) may be substituted for square brackets ([]) to enclose 
directory, and a period (.) may be used in place of the semicolon (;) 
to separate type and version. The total length of a full file 
specification string may not exceed 252 characters. 


VAX-11 RMS converts lowercase characters to uppercase and removes 
space, tab, and null characters from a file specification, except for 
characters within quoted strings (such as "“access-control-strings", 
"“foreign-file-spec-strings", and "task-spec-strings"). 


The fields of the full file specification defined below emphasize the 
fields unique to network processing. 


node-spec 


ACCESSING THE NETWORK 


identifies the target node and specifies which 


account on 


that node to use. If you specify the 


name (or number) of the local node, the connection 
is made to the local node by DECnet as if it were 


a remote node 


The length of 
including the 


The format of 


nodename 


a 
re 


a 


node-spec is 3 to 61 characters, 
quired double colon delimiter. 


node-spec is: 


"access-control-string":: 


logical-nodename 


Each component of the node-spec is defined below: 


nodename 
(1-6 char) 


logical- 
nodename 
(1-15 char) 


access- 
control- 
string 
(0-42 char) 


specifies a node in the network. 
The node name consists of 
uppercase alphanumeric characters. 
If the node name is all numeric, 
it will be interpreted as the node 
number (where 0 represents’ the 
local node). (For compatibility 
with future versions of DECnet, 
you should avoid the use of node 
numbers.) You may prefix the node 
name with an underscore character 
( ) to designate that it is not a 
candidate for logical node name 
translation. 


specifies a logical name for a 
node in the network. Refer to 
Section 2.3 for rules governing 
the use of logical node names. 


is an optional quoted character 


string containing login 
information that is sent to the 
remote node. This String 
designates the remote account 


under which programs (or _ tasks) 
will execute on your behalf or 
remote files will be accessed to 
perform the functions that you 
request. If you omit the access 
control String, the login 
information sent to the remote 
node is the default access control 
string for that node as_ specified 
by the local System Manager (see 
Section 2.2). 


An access control string is 
expressed in either of the 
following formats: 


"username password" 


"username password account" 


device, 
directory, 
filename, 
type, and 
version 


foreign-file- 
spec-string 
(1-127 char) 
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For a VAX/VMS node, either format 
is acceptable, but the shorter 
form is generally used because 
VAX/VMS ignores the account name 
subfield when you log in. You 
should refer to the appropriate 
DECnet documentation for the 
access control string format for 
nodes other than VAX/VMS. 


Space and tab characters (or 
multiples thereof) delimit 
username, password, and account. 
Therefore, each substring within 
the access-control-string may 
contain any characters except the 
quote, space, and tab characters. 


are five optional fields that collectively 
identify the file to be accessed on a remote node. 
The definitions and syntax rules for these fields 
are the same for network use as for local file 
access, including the specification of seven 
levels of subdirectories and the use of wild card 
characters where valid. If the syntax of the file 
specification differs from that of VAX/VMS, use 
the foreign-file-spec-string format. 


If a device or directory is not specified in the 
file specification string, default values are 
supplied by the target node, which uses’ the 
conventions of its operating system. If the 
target node is VAX/VMS, all defaults apply as 
though the user had logged in at the remote node 
using the access control information implicitly or 
explicitly supplied. 


The VAX-11 Record Management Services Reference 
Manual contains a detailed explanation of the 
syntax for VAX/VMS file specifications. 


is a quoted character string that identifies the 
file to be accessed on a remote node. The syntax 
of the file specification must be in the format 
recognized by the operating system of the remote 
node. 


When you put a file specification between 
quotation marks, the VAX-11 RMS facility at the 
local node performs no syntax checking or logical 
name translation. Rather, the local node passes 
the file specification intact to the remote node 
where it is interpreted. Use the quoted string 
format when the file specification syntax of the 
remote node differs from that of VAX/VMS. For 
example, a RSTS file specification may contain a 
dollar sign (S$): 


$ TYPE KANSAS::"SSTART.CTL" 


task-spec- 
string 
(2-32 char) 
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is a quoted string that identifies the remote task 
to which you attempt the logical link connection. 
You identify the task by object type. An object 
type is a discrete identifier for either a user 
task or a known object on a remote node. Object 
types have two forms: 


e Zero (0) plus a name or TASK plus a name _ (for 
example, "O=TEST2" or "TASK=TEST2") 


e Nonzero without a name (for example, "17="_ or 
"FAL=", where FAL in this case is the name 
specified for object 17 by the NCP command 
DEFINE OBJECT) 


Nonzero network objects (known objects) are 
intended for generic process addressing over the 
network. For example, a program written to 


establish a logical link with the FAL object may 
send a request by addressing object type 17. 
User-written tasks are usually addressed as object 
type 0 plus a name, but they may also be addressed 
with a nonzero object type alone. (Refer to the 
Introduction to DECnet manual for a _ complete 


discussion of object types and their use.) 


Appendix A lists the object type numbers’ reserved 
for standard DECnet services and those available 
for user-written programs. 


To eStablish a logical link connection with a 
remote task addressed as object type 0, use either 
of the following forms of task specification 
string, where taskname is one to nine characters 
in length: 


“TASK=taskname" 
"O=taskname" 


If the remote node is a VAX/VMS system, the 
taskname string represents the file name of a DCL 
command procedure to be executed at the remote 
node. (If the remote node is not a VAX/VMS 
system, the maximum length of the task name _ that 
it accepts may be different.) The command 
procedure can complete the logical link itself or 
it can include a DCL RUN command to execute a 
program that completes the logical link. 


To address the remote task by a nonzero object 
type, use the following form as the task 
specification string, where n is an object type 
number (in the range of 1 to 255) and xyz is an 
object name equated to a number via the NCP 
command DEFINE OBJECT: 


ran 
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Examples of network file specifications 
1. DALLAS::TEST.DAT 


Use this file specification to access the file TEST.DAT on 
node DALLAS. 


2. TRNTO::DMA2: [INVENTORY] TEST. DAT; 3 
TRNTO"KC JONES": :DBA1: TEST. DAT; 3 


The first of these two file specifications provides no 
explicit access control information but the second one does. 


3. KANSAS::"SSTART.CTL" 
TOPS20"KC JONES APOLLO": :"A-VERY-LONG-FILE-NAME.TEST.5" 


These examples illustrate the use of quotation marks when the 
remote node's file specification syntax differs from that of 
VAX/VMS. 


Examples of network task specifications 
1. BOSTON: :"TASK=TEST2" 


This specification identifies the task TEST2 by using the 
TASK= form for specifying remote tasks. 


2. BOSTON"JOHN SMITH": :"0=TEST2" 


This example is the same as the one above, except that access 
control information is provided and the alternative 0O= form 
for specifying a task is used. 


3. DALLAS::"150=" 


This specification identifies the user-defined network object 
by object type (150). 


2.2 ACCESS CONTROL 


Access control is the control that a node exercises over inbound 
logical link connections. The terms inbound and outbound refer to the 
direction of the logical link connection request. A node receives and 
processes inbound requests; it processes and sends outbound requests. 
This distinction is useful for discussing access control as it relates 
to VAX/VMS nodes in a network. Refer to appropriate DECnet 
documentation if the node to which you want to connect is other’ than 
VAX/VMS. 


When DECnet-VAX software sends an outbound connection request in 
response to either a remote file access or a_task-to-task 
communication operation, certain access control information may be 
necessary to connect successfully to the remote node and log in. As 
in logging in at your local VAX/VMS node, you can supply specific 
access control information in the form of a user name and password 
that the remote node recognizes. The remote node processes inbound 
connection requests containing this information to verify that you are 
a valid user of the system. 


Upon receiving an inbound connection request, DECnet-VAX software at 
the remote node creates a process and starts the LOGINOUT image, which 
verifies your access rights by checking the User Authorization File 
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(UAF). A user account record is set up for you beforehand within this 
file by the System Manager. Generally, every time you access a 
network node, your status as a valid user of that node will be 
verified against the information contained in the UAF. In this 
instance, access control provides one form of network security. One 
exception to this form of access control checking is in nontransparent 
task-to-task communication wherein a task can receive multiple inbound 
connection requests (see Chapter 7). 


There are two ways to supply access control information for network 
access: 


e You can explicitly specify an access control string as part of 
a file or task specification in the node field. 


e You can have the local node forward default or null access 
control information to the remote node. 


In either case, DECnet software sends this information to the remote 
node which in turn processes the inbound connection request and, if 
this information is valid, grants access. If you include an access 
control string as part of a node specification, this information is 
always sent directly to the remote node. The privileges associated 
with either the local account under which your process is running or 
the specified remote account are of no concern to the local DECnet-VAX 
implementation. Figure 2-1 illustrates the access control processing 
that takes place for a simple DCL command. 


$ COPY TEXT.NEW TRNTO "WHITE XYZ"::DBA1:TEXT.TXT 





RMS 
Processing 







Remote 
Node TRNTO:: 







Local Node 
BOSTON:: 





LOGINOUT.EXE 
Runs 


DECnet-VAX 
Software 


DECnet-VAX 
Software 


















(If Access 
Information 
Checks Out) 


Access [~ 


Validity 
Checking | 





FAL Processing "| 












Command Procedure 
SYS$SYSTEM: FAL.COM 
is executed 





Key: 
“ WHITE XYZ” | 






FAL.EXE 
Runs 










FAL.LOG 


TEXT.TXT 
| is produced 






ee ee | 


ZK-836-82 


Figure 2-1: Remote File Access Using Access 
Control String Information 
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When explicit access control information is not provided in the 
connection request, DECnet-VAX software uses the remote node name 
specified in the connection request as a key to locate the appropriate 
record in the local Configuration Data Base. This record contains 
default access control information applicable to the remote node. 
Your System Manager creates this entry when establishing the 
Configuration Data Base. (Refer to the DECnet-VAX System Manager's 
Guide for additional information on the Configuration Data Base.) 
Depending on the privileges required by the object with which you want 
to connect and those of the user process (see Figure 2-3), one of 
three possible sets of default access control information is sent to 
the remote node: default privileged, default nonprivileged, or null. 
Because these defaults are node parameters, all privileged operations 
requested with default access control for a given node run under the 
same default account. The same is true for nonprivileged operations 
requested with default access control. Figure 2-2 illustrates the 
access control processing that takes place for the same DCL command as 
in the example in Figure 2-1, except that the DCL command does not 
specify an access control string. 
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Figure 2-2: Remote File Access Using Default 
Access Control Information 


Note that, in DECnet-VAX usage, nonprivileged means no_ privileges 
other than TMPMBX and NETMBX. Privileged means any privileges in 
addition to TMPMBX and NETMBX. The context for network-related 
privileges is the NCP command DEFINE OBJECT. Normally, task-to-task 
communication and remote file access are nonprivileged operations. 
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The Configuration Data Base may also define privileges associated with 
network operations such as task-to-task communication. The System 
Manager may create object entries with associated privileges. There 
must be a separate entry for every numbered object that might be 
requested ("n="). 


If, on an outbound connect to an object, you attempt a privileged 
connection and you do not have sufficient privilege, then you get null 
access control. On an inbound connection to a nonzero object, any 
access control information you specify is used. If you do not specify 
access control information, then one of the following will occur: 


e If access control information is associated with the object in 
the Configuration Data Base, then it is used. 


e If no accesS control information is associated with the 
object, then the access control for the local nonprivileged 
network account (if any) is used; otherwise, no information 
is used. 


Access control is not checked for connections to running tasks that 
have declared names or object numbers (see Section 7.4.1). Figure 2-3 
illustrates the process used to determine what access control 
information (if any) is used for outbound and inbound connections to 
objects. (Note that in order to use default access control for a 
privileged account, the process that makes the request must have at 
least the same local privileges.) Local privileges are completely 
independent of remote privileges. The DECnet-VAX System Manager's 
Guide provides a more detailed discussion of access control, network 
privileges, and the Configuration Data Base. 
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2.3 USING LOGICAL NAMES 


The use of logical names for network operations allows you to refer to 
network file and task specifications without using actual names that 
you give these elements. Logical names serve as a kind of shorthand 
for specifying all or a portion of a full file specification. The 
inherent flexibility in using logical names allows you to pass file 
specifications defined at the DCL level to an executing image at run 
time. For example, logical names allow a program to access local or 
remote files without changing the program. You can also use logical 
names to conceal access control information from other users by 
embedding it in a logical name defined in the process logical name 
table. Logical names provide convenient and powerful multilevel 
access control specification. 


The rules that govern the use of logical names for network operations 
are as follows: 


e Both the device name and node name elements of a full file 
specification string can be logical names. However, once a 
node specification is encountered during file parsing, the 
device name that follows will be treated as a logical name 
only if it translates to an equivalence string that was 
entered in user mode in the process logical name table. 
Otherwise, the device name is passed unaltered to the remote 
node, where it is subject to logical name translation. 


e A logical name appearing in the device name position can 
supply any file specification string elements when translated. 


e A logical name appearing in the node name position can supply 
only a node-spec when translated. Therefore, its equivalence 
String must end with a double colon. 


e An access control string associated with a logical node name 
becomes the new access control string for the node-spec of the 
equivalence string, even if the node-spec contained an access 
control string. Thus, you can easily specify a default (or 
override any) access control string defined for the node-spec 
resulting from logical name translation. 


e After a logical node name is translated, the new node name 
becomes a candidate for logical node name translation. 


e A maximum of ten logical device name translations and _ ten 
logical node name translations is permitted. If you exceed 
these limits, an RMS error (RMSS$ _LNE) is returned. 

Examples of Logical Names 

1. $ DEFINE NEW YORK NYC:: 

$ DEFINE TORONTO TRNTO:: 


$ DEFINE FILE TORONTO: :DBA1: [INVENTORY. COM]COPYTEST. COM 
$ TYPE FILE 


This command displays (at the local node) file COPYTEST.COM 
in directory [INVENTORY.COM] on remote node TRNTO. 


2. $ DEFINE A TRNTO::DBA1: [INVENTORY. COM] 
$ TYPE A:COPYTEST.COM 


This command displays file COPYTEST.COM in an alternate 
manner. 
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3. $ DEFINE B TRNTO:: . 
$ TYPE B::DBA1: [INVENTORY.COM]COPYTEST.COM 


This command displays file COPYTEST.COM in still another 
manner. 


$ DEFINE TORONTO TRNTO:: 

$ DEFINE NODE "TORONTO""TEST RESULTS""::" 
$ DEFINE DEVICE NODE::DBAI1: 

$ DEFINE REMOTE DEVICE: [FINAL.RESULTS] 

$ TYPE REMOTE: TEST. DAT 


This command displays file TEST.DAT - in directory 
[FINAL.RESULTS] on node fTRNTO. The file specification was 
expanded as follows: 


$ TYPE REMOTE: TEST.DAT 

DEVICE: [FINAL. RESULTS] TEST. DAT 

NODE: : DBA]: [FINAL. RESULTS] TEST.DAT 

TORONTO"TEST RESULTS": :DBA1: [FINAL. RESULTS] TEST.DAT 


TRNTO" TEST RESULTS": :DBA1: [FINAL. RESULTS] TEST.DAT 


2.3.1 Iterative Translation 


The node name portion of a node _ specification is translated 
recursively. For example: 


$ DEFINE ALPHA BOSTON:: 

S$ DEFINE BETA ALPHA:: 

$ DEFINE C "BETA""FRED XJ5""::DM1: [TEMP]" 
§$ TYPE C:FILE.DAT 


This command displays file FILE.DAT in directory [TEMP] on _ node 
BOSTON. The file specification was expanded as follows: 


$ TYPE C:FILE.DAT 
Surlenees XJ5"::DM1: [TEMP] FILE.DAT 
ALPHA"FRED XJ5"::DM1: [TEMP] FILE. DAT 
BOSTON"FRED XJ5"::DM1: [TEMP]FILE.DAT 


When logical node names are translated iteratively, the access control 
information first translated overrides subsequent access’ control 
information. For example, 


$ DEFINE TORONTO "TRNTO""TEST RESULTS""::" 

$ DEFINE TEST1 "“TORONTO""TEST 1001""::DBA1:" 
$ DEFINE TEST2 TORONTO: : DBA2: 
$ 


TYPE TEST1:PROC.001,TEST2:PROC.002 


In the above example, TEST1 translates to TRNTO"TEST 1001"::DBAl1: and 
TEST2 translates to MTRNTO"TEST RESULTS"::DBA2:. Note that TORONTO 
would be an invalid node name were it not a logical name that 
translated to a node specification containing a node name of one to 
six characters. 
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2.3.2 Names Prefixed by an Underscore Character 


Device names and node names that are prefixed by an underscore 
character ( ) are not candidates for logical name translation. 
However, if you prefix the underscore character to a name, it is not 
considered part of the name (for example, BOSTON is a valid node name 
in this respect). For example: 


DEFINE BOSTON TRNTO:: 

TYPE BOSTON: :A.DAT, BOSTON: :B.DAT 
DEFINE/USER DBAO DBA2: 

TYPE BOSTON: :DBA0O:C.DAT, BOSTON:: DBAO:D.DAT 


TU 7 1 


In the example above, A.DAT comes from node TRNTO, B.DAT comes from 
node BOSTON, C.DAT comes from DBA2 on node TRNTO, and D.DAT comes from 
DBAO on node BOSTON. Note that if the logical name DBAO were not 
placed in the process table in user mode, it would not have been 
translated at the local node for the file specification containing 


C.DAT. 


2.4 NETWORK COMMAND TERMINALS 


DECnet-VAX network command terminals are implemented via the VAX/VMS 
remote command terminal facility. This facility permits a single user 
to establish communication with a remote VAX/VMS node and to use _ the 
facilities of that system while physically connected to the local 
node. By means of this link, you can temporarily become a local user 
of the remote node and thereby perform functions that the remote node 
allows its local usSers to perform. 


To establish communication with a remote VAX/VMS node, use the DCL 
command SET HOST. The format for this command is as follows: 


SET HOST nodename 
In this command, nodename is defined as follows: 


nodename is a l- to 6-character name (or number) specifying 
the remote node at which you want to log in. 


The remote system will prompt for a user name and password, and, if 
this information is valid, it will cause you to be logged in at the 
remote node. There is no special control character handling (other 
than CTRL/Y) for remote command terminal operations. To return 
control to your local node, type LOGOUT; the following message will 
appear, indicating that control has been transferred to your local 
node: ’ 


SREM-S-END, control returned to node _nodename:: 


NOTE 


Repeated pressing of CTRL/Y rapidly will 
generate a prompt asking if the remote 
connection should be~ broken. If you 
answer "Yes" to the prompt, control will 
return to the local node. This is 
useful if for some reason you cannot 
return to the local node properly. 


ACCESSING THE NETWORK 


The following command sequence illustrates the operation of remote 
command terminals for our network example (the name of the local node 
is BOSTON): 


$¢ SET HOST TRNTO 
Usernamei SMITH 
Fassword 


Welcome to VAX/VMS Version V2.0 om mode TRNTO?: 


$ LOGOUT 
SMITH lossed out st B-MAY-B2 12°331°355.49 


ZREM-S-ENDs control returned to mode BOSTON: 3 


$ 
+ 
¢ 


¢ 


Once logged in at a remote node, you can use the SET HOST command to 
establish communication with another node. In the above example, 
after logging in at node TRNTO, you could type SET HOST DENVER, which 
would cause you to be logged in at node DENVER. Note that when you 
are logged out at node DENVER, control returns to node MTRNTO. Refer 
to the VAX/VMS Command Language User's Guide for a complete discussion 
of the SET HOST command. 


CHAPTER 3 


REMOTE FILE ACCESS USING DCL 


Most VAX/VMS DCL commands allow you to perform file operations at a 
remote node. These commands enable you to obtain directory listings, 
manipulate files, and execute command procedures over the network. 
The DCL commands described in this chapter use VAX-11l1 RMS to perform 
the following network file operations: 


e List directories located on a remote node 

e Copy files to and from remote nodes and between remote nodes 
e Append files to a file 

e Delete and purge files from a remote node 


e Open, read, write, and close files at a remote node from a 
command procedure 


e Submit command procedure files for execution at the remote 
nodes where they reside 


e Print files at the remote nodes where they reside 
e Type files located on a remote node 

e Sort and merge remote files 

e Search remote files 


e Obtain file specification or attribute information about 
remote files 


@e Compare two files for differences 


@e Analyze the structure of remote VAX-11 RMS files 


e Convert files from one format to another while copying the 
result to or from a remote node 


e Dump the contents of remote files for inspection 
e Perform backup operations on remote VAX/VMS disk files 


Many VAX/VMS DCL commands permit access to remote files. These 
commands fall into the following categories: logical name operations, 
file operations, lexical functions, and record access operations. 
This chapter defines the commands (and relevant command and file 
qualifiers) that you can use over the network. The descriptions of 
the commands include restrictions on the use of certain commands in a 
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heterogeneous network environment (because of features not available 
on remote systems). For complete descriptions of these commands, 


3.1 ACCESSING THE NETWORK USING DCL COMMANDS 


A VAX/VMS interactive or batch user is able to perform a variety of 
network file operations through DCL commands. Conceptually, accessing 
the network at this level is the same as using DCL directly for local 
operations. For most DCL commands, you need only include a node name 
as part of the standard VAX/VMS file specification to denote a _ remote 
file. In addition, NETMBX and TMPMBX privileges are required to 
execute most of the commands described in this chapter. 


Table 3-1 summarizes the functions of DCL commands that are commonly 
used to access remote files in a network environment. 


Table 3-1: DCL Command Summary 


Type of Operation and | Function 
Command Statement 
Logical Name Operations 


ASSIGN Associates a file specification, 
node name, or device name with a 
logical name for subsequent use 
in commands and programs at the 
local node 


DEASSIGN ; Cancels a logical name 
assignment made with the ASSIGN 
or DEFINE command 


DEFINE Creates a logical name for use 
at the local node with an 
equivalence name string that is 
a partial or full file 
specification (similar to the 
ASSIGN command) 


SHOW LOGICAL Displays the current assignments 
for logical names and 
equivalence names made by the 
ASSIGN or DEFINE command 


SHOW TRANSLATION Searches logical name tables for 
a specific logical name and 
displays the equivalence name of 
the first match found 


File Operations 


ANALYZE/RMS FILE Analyzes the internal structure 
co of a VAX-11 RMS file, optionally 
generating an FDL (File 

Definition Language) file 





(continued on next page) 
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Table 3-1 (Cont.): DCL Command Summary 


Type of Operation and Function 
Command Statement 


APPEND Adds the contents of one or more 
files to the end of another file 


BACKUP Performs save and . restore 
operations on local files using 
a saveset residing on a_ remote 
VAX/VMS node. 


CONVERT Copies records from one file to 
another file, changing the 
organization and record format 
to that of the second file (if 
it exists) or creating a new 
file using the file attributes 
specified in an FDL file 


COPY Copies one or more files to or 
from a remote node into one or 
more additional files 


CREATE Creates a sequential disk file 
from records that follow the 
command in the input stream 


DELETE Deletes one or more remote files 


DIFFERENCES Compares the contents of two 
files and produces an output 
file that lists any differences 

found 


DIRECTORY Displays the file name and 
optional file attribute 
information about a remote file 
or group of remote files 


DUMP/RECORDS Displays the contents of a 
remote file in the data format 
specified 


Combines two or more similarly 
sorted remote files into one new 
file 


PRINT/REMOTE Queues for printing one or more 
files at the nodes where they 
reside 


PURGE Purges one or more remote files 
SEARCH Searches one or more files and 


lists all occurrences of one or 
more specified strings 





(continued on next page) 
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Table 3-1 (Cont.): DCL Command Summary 


. Type of Operation and Function 
; Command Statement 


Reorders records in a_ remote 
file and creates a new output 
file (or an address file to 
access the records) 


SUBMIT/REMOTE Queues for execution one or more 
command procedures at the nodes 
where they reside 


Displays the contents of 
remote file or files 


Lexical Functions 


FSFILE ATTRIBUTES Returns attribute information 
about a remote file 


FSPARSE Returns a partial or full file 
specification for a remote file 


FSSEARCH Returns the full file 
specification for the next 
remote file that matches’ the 
given wild card file 
specification 


Record Access Operations 


CLOSE Closes a remote file previously 
opened by the OPEN command 


OPEN Opens a remote file for reading 
or writing at the command level 


READ Reads a Single record from a 
remote input file 


WRITE Writes a single record to a 
remote output file 





3.2 LOGICAL NAME COMMANDS 


Several DCL commands permit you to create, delete, and display logical 
names. Although logical name manipulation is performed locally by the 
commands described in this chapter, use of logical names in file 
specifications in other DCL commands does affect the network. 
Consequently, the logical name support commands are described below. 


3.2.1 ASSIGN, DEASSIGN, and DEFINE 


The ASSIGN, DEASSIGN, and DEFINE commands allow you to generate 
logical names for nodes and devices for use in file specifications. 
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These commands provide a convenient way to use logical file 
specifications without having to define physical device 
specifications. When used for network operations, these commands 
support all command and file qualifiers that you would normally use 
locally. 


Examples 
1. $ DEFINE TORONTO TRNTO: :DBAO: [DECNET.DEMO.COM] 


This DEFINE command places the logical name TORONTO in the 
Process logical name table with an equivalence name of 
TRNTO: :DBAO: [DECNET.DEMO.COM]. 


2. $ DEFINE LOCAL "BOSTON""JOHN SMITH JKS""::" 


This DEFINE command places the logical name LOCAL in the 
process logical name table with a remote node equivalence 
name of BOSTON"JOHN SMITH JKS"::. To satisfy conventions for 
local DCL command string processing, you must use three sets 
of quotation marks, so that access control information will 
be enclosed in one set of quotation marks in the equivalence 
name. 


3. $ ASSIGN DALLAS::DB0O: DATA 
This ASSIGN command associates the logical name DATA with the 
device specification DBO on remote node DALLAS. Subsequent 


references to the logical name DATA result in references to 
the disk on the remote node. 


4. S$ DEASSIGN DATA 


This DEASSIGN command cancels the logical name assignment 
made in the above example. 


3.2.2 SHOW LOGICAL and SHOW TRANSLATION 


The SHOW LOGICAL command displays current logical name assignments and 
the SHOW TRANSLATION command displays the result of translating a 
logical name. For a discussion of the use of logical names for 
network operations, see Chapter 2. 


Examples 
1. $$ SHOW LOGICAL 


This SHOW LOGICAL command displays the current contents of 
the process, group, and system logical name tables. 


2. $ SHOW TRANSLATION MASTER 
This command causes the logical name tables to be searched 


for the logical name MASTER, and displays its current 
equivalence name. 


3.3 COMMANDS FOR FILE HANDLING 


Many DCL commands that contain file specifications can be used to 
access files stored on remote nodes. The following is a list of DCL 
commands that are useful in a network context and are supported in 
part or in full in that environment. This list notes restrictions on 
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using certain command qualifiers and file qualifiers when entering 
particular commands in a network context. Complete descriptions of 
the file-handling commands appear in the VAX/VMS Command Language 
User's Guide. 
This command is supported only for the examination of files 
generated by VAX-11 RMS or RMS-1ll. 
APPEND input-file-spec[,...] output-file-spec 


BACKUP input-specifier output-specifier 
This command is supported only to access savesets located on 
remote VAX/VMS' nodes. An input or output specifier that 
includes a remote node name must also include the _ file 
qualifier /SAVE_ SET. 


The copy, compare, and journal operations are not supported. 
CONVERT input-file-spec[,...] output-—file-spec 


COPY input-file-spec[,...] output-file-spec 
The following file qualifiers are not supported if the 
output file is on a remote node: 


/ (NO] OVERLAY 
/{NO]REPLACE 


CREATE file-spec 


The /DIRECTORY qualifier is not supported. 
DELETE file-spec[,...] 
DIFFERENCES master-file-spec [revision-file-spec] 


DIRECTORY [file-spec[,...]] 


The command qualifier /FULL is supported except for the 
file identification number which is displayed as <unknown>. 


MERGE input-file-specl,input-file-spec2[,...] output-file-spec 


DUMP/RECORDS [=(option[,...])] file-spec 
The following command qualifiers are not supported: 
/ ALLOCATED 
/ BLOCKS 
PRINT/REMOTE file-spec[,...] 


No other qualifiers may be used with /REMOTE. 
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PURGE file-spec[,...] 
SEARCH file-spec[,...] search-string[,...] 


SORT input-file-spec[,...] output-file-spec 


The /RSX11 qualifier is not supported. 


No other qualifiers may be used with /REMOTE. 


The DCL commands listed below are not supported for access to files on 
remote nodes: 


@ 
RENAME 


RUN 
SET DEFAULT 
UNLOCK 


The following subsections describe in more detail the use of DCL 
commands for handling files over the network. Note that if you do not 
specify an access control string in the file specification in a DCL 
command, the default DECnet account at that node is accessed if it 
exists. 


3.3.1 ANALYZE/RMS FILE 


Use the ANALYZE/RMS FILE command to analyze the internal structure of 
a remote VAX-11 RMS or RMS-11 file. You can specify the command 
qualifier /FDL to generate an FDL (File Definition Language) file from 
the data file. Using other command qualifiers, you can check the file 
structure for errors, generate a statistical report on the file's 
Structure and use, or enter interactive mode to explore the structure 
of the file. You can specify only one of these command qualifiers in 
each command. 


Examples 


1. $ ANALYZE/RMS FILE DENVER: :DB1: [PROD] RUN.DAT 


This ANALYZE/RMS FILE command analyzes the Structure of the 
file RUN.DAT residing at remote node DENVER. 


2. $ ANALYZE/RMS FILE/FDL/OUTPUT=TEST. FDL 
$ File(s): DENVER::DB1: [PROD]RUN.DAT 


This ANALYZE/RMS FILE command analyzes the structure of the 
file RUN.DAT at remote node DENVER and generates the FDL file 
TEST.FDL at the local node. 
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3.3.2 APPEND and COPY 


Use the APPEND command to add the contents of one or more _ specified 
input files to the end of a specified output file. Use the COPY 
command to create a new file from one or more existing files. 


Examples 


1. $$ COPY BOSTON: :DMA2:TEST.DAT;5 
$_ To: TRNTO: : DBA1: [MODEL. TEST] TEST. DAT/ALLOCATION=50 


This COPY command copies the file TEST.DAT;5 on device DMA2 
at node BOSTON to a new file named TEST.DAT at remote node 
TRNTO. The /ALLOCATE qualifier initially allocates 50 blocks 
for the new file TEST.DAT at node TRNTO. 


2. $$ APPEND/LOG BOSTON"JOHN SMITH JKS": :DEMO1. DAT, DEMO2.DAT 
$_ To: TRNTO: : DBA1: [MODEL. TEST] TEST. DAT 


This APPEND command adds the contents of the files DEMO1.DAT 
and DEMO2.DAT at remote node BOSTON to the end of file 
TEST.DAT at remote node TRNTO. The /LOG qualifier displays 
the fully expanded names of the files used. 


3. $ COPY SAMPLE.EXE DALLAS: : DBO: [117,10] SAMPLE. EXE/CONTIGUOUS 


This COPY command copies the file SAMPLE.EXE on the _ local 
node to a file with the same name at remote node DALLAS. The 
/CONTIGUOUS qualifier indicates that the output file is to 
occupy consecutive physical disk blocks. 


4. $ COPY DALLAS::T1.DAT,T2.DAT,T3.DAT *.* 
$ COPY *.* TRNTO::*.* 


The first COPY command copies the three files T1.DAT, T2.DAT, 
and 1T3.DAT on remote node DALLAS to the local node while 
preserving the names of the files. The second example is a 
more generalized form of the COPY command. All files within 
the user directory at the local node are copied to the remote 
node MTRNTO. The new files will have the same names as the 
input files. . 


3.3.3 BACKUP 


You can use the BACKUP command to save local files in a BACKUP saveset 
residing on a remote VAX/VMS node. You can also use this command to 
restore at the local node files that were previously saved in a 
saveset on a remote VAX/VMS node. Use BACKUP/LIST to display the 
names and attributes of files cataloged in a remote saveset. The 
remote BACKUP saveset cannot be on magnetic tape; it must reside on 
disk. 


Examples 


1. $§ BACKUP 
$ From: DBl: [SCHED]*.* 
$ To: DENVER: :DBA2: [SAVE]SCH.BCK/SAVE_SET 


This BACKUP command saves the files in the directory SCHED on 
disk DBl at the local node in the BACKUP saveset SCH.BCK at 
remote node DENVER. The /SAVE SET qualifier is required to 
identify the output specifier as a saveset on a Files-1ll 
medium. 
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2. $ BACKUP/LIST DENVER: :DBA2: [SAVE]SCH.BCK/SAVE_ SET 


This BACKUP command lists the BACKUP summary information, the 
original BACKUP command used, and the file name, size and 
creation date for each file in the saveset created in example 
1. The /SAVE SET qualifier is required to identify the input 
specifier as a saveset on a Files-11l medium. 


3.3.4 CONVERT 


Use the CONVERT command to transfer records from a source data file to 
a second data file, which can differ in file organization and format 
from the first. You can use this command to transfer files to or from 
a remote node while altering file attributes. If the output file 
exists, the Convert Utility (CONVERT) changes the organization and 
format of the data from the input file to that of the output file. If 
the output file does not exist, the Convert Utility creates it from 
the file attributes specified in an FDL (File Definition Language) 
file. You can also use the CONVERT command to copy files to a remote 
node or to retrieve them without modifying file attributes. However, 
CONVERT transfers the file record by record and thus does not’ use 
block I/0. 


The Convert Utility is described in the VAX-11 Record Management 
Services Utilities Reference Manual. 


Examples 
1. $ CONVERT/FDL=TEST.FDL TRNTO::DBA1: [EXP]SUB.DAT CUM.DAT 


This CONVERT command creates a new sequential file CUM.DAT 
with stream record format at the local node, according to the 
specification in the previously created FDL file, TEST.FDL. 
The input file SUB.DAT at remote node TRNTO is sequential 
with variable-length record format. The Convert Utility 
copies records from SUB.DAT to CUM.DAT, changing the format 
of the records. 


The contents of the FDL file TEST.FDL are as follows: 


SYSTEM 
SOURCE vax/vms 
FILE 
ORGANIZATION sequential 
RECORD 
BLOCK SPAN yes 
CARRIAGE CONTROL carriage return 
FORMAT stream 
SIZE 0 


2. $ CONVERT MASTER.DAT DENVER: :DB1: [PROD] MASTER. SAV 


This CONVERT command creates a new file called MASTER.SAV at 
remote node DENVER from the file MASTER.DAT at the local 
node. Because the /FDL qualifier is not used, the new file 
has the same file organization and record format as the 
original file. The action of this CONVERT command is similar 
to the function performed by the COPY command. However, 
CONVERT transfers the file record by record and thus does not 
use block I/0. 
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3. $ CONVERT/APPEND SALES.TMP KANSAS::[200,2]SALES.CMD 


This CONVERT command causes records from the file SALES.TMP 
at the local node to be added sequentially to the end of the 
output file SALES.CMD at remote node KANSAS. The file 
SALES.TMP is sequential with variable-length record format, 
and the file SALES.CMD is sequential with stream _ record 
format. When the Convert Utility loads records from the 
input file to the output file, it changes the record format. 


3.3.5 CREATE 


Use the CREATE command to create sequential disk files on a_e remote 
node. 


Example 


$ CREATE TRNTO::DBA1: (MODEL. TEST] TEST. DAT 
1 

Ag 

333 

4444 

“Zz 

$ 


The CREATE command creates a sequential file named TEST.DAT 
that consists of the characters entered on the lines 
following the CREATE command. The CTRL/Z entry indicates the 
end of the file. . 


3.3.6 DELETE and PURGE 


Use the DELETE command to delete one or more files from a mass Storage 
volume on a remote node. The DELETE command requires that an explicit 
version number be included in a file specification unless the file 
specification is delimited by quotation marks. A null version number 
(;) or a version number of zero (;0) implies the highest version of 
the file. Use the PURGE command to delete ali but the 
highest-numbered version or versions of one or more files residing at 
remote nodes. 


Examples 


1. $ DELETE/LOG 
$ File: TORONTO: :DBAO: [100,5]WORKORDER. DAT; 3,OUTPUT.FIL;2 


This DELETE command deletes the files WORKORDER.DAT;3 and 
OUTPUT. FIL;2 from device DBAO at remote node TORONTO. The 
/LOG qualifier displays the file specification of each file 
deleted. Note that TORONTO is a logical name. 


2. $ DELETE DALLAS"FRED R2D2"::DKO0: [305,321] DECODE.LIS;1 


This DELETE command deletes the file DECODE.LIS;1 in 
directory [305,321] on device DKO at remote node DALLAS. 


3. $ DELETE/CONFIRM 
$ File: TRNTO: : [SAM.OBJ]A.OBJ;,A.EXE;, [SAM.LIS]JA.LIS; 


This DELETE command queries the user whether or not each of 
the successive files on remote node TRNTO should be deleted. 
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4, $ DELETE QUEBEC::"DX1:DEAL.BIG" 
$ DELETE QUEBEC::DX1:DEAL.BIG; 


Both of these DELETE commands delete the file DEAL.BIG on 
device DX1l at remote node QUEBEC. Note that the DELETE 
command requires an explicit version number in ae file 
specification. The file to be deleted is on a remote node 
whose file syntax does not recognize version numbers. 
(QUEBEC is an RT-11 node.) Therefore, the file specification 


should be enclosed in quotation marks or entered with a null 
version number (that is, a trailing semicolon). 


5. $ PURGE TRNTO::DBA1: [EXAMPLE]*.LIS/KEEP=2 


This PURGE command deletes all but the two highest-numbered 
versions of each file of the type LIS in the directory 
EXAMPLE on remote node TRNTO. 


3.3.7 DIFFERENCES 


Use the DIFFERENCE command to compare the contents of two files 
(either of which can be local or remote) on a record-by-record basis. 
The command produces an output file listing any differences. 


Examples 
1. $ DIFFERENCES BOSTON: :DBA2:TEST.DAT TRNTO::DBAl1: [PGM]TEST.DAT 


This command compares two remote files and displays any 
differences found. The first file is TEST.DAT on remote node 
BOSTON and the second file is TEST.DAT on remote node TRNTO. 


2. $ DIFFERENCES BOSTON::TEST.DAT . 
This command compares the two highest versions of the file 


TEST.DAT in the nonprivileged default DECnet account on 
remote node BOSTON. 


3.3.8 DIRECTORY 


Use the DIRECTORY command to list files and their attributes in a 
directory on a remote node. 


Examples 
1. $ DIRECTORY TRNTO: :DBA1: [DOE] LOGIN.COM 


This DIRECTORY command lists all versions of the file 
LOGIN.COM under directory DOE at remote node TRNTO. 


2. $ DIRECTORY/DATE/SIZE=ALL TRNTO::DBA1: [DOE...]*.COM 


This DIRECTORY command lists all versions of all files with a 
file type of COM in all subdirectories of [DOE] on remote 
node TRNTO. The listing includes the creation date with each 
file, and the file size both in blocks used and in blocks 
allocated for each file. 
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3. $ DIRECTORY/FULL BOSTON: :*VAX*.* 


This DIRECTORY command displays full directory information 
for each file whose file name contains the string "VAX" in 
the nonprivileged default DECnet account on node BOSTON. 


4. $ DIRECTORY/SINCE=TODAY BOSTON"JOHN SMITH JKS"::[.MEMO]W3% 


This DIRECTORY command lists each file created today in the 
user's subdirectory MEMO whose file name begins with "W" and 
contains three characters (for example, W03.DOC, WWW.TMP). 


5. $ DIRECTORY TORONTO: : 


This DIRECTORY command lists all the files cataloged in the 
directory associated with the default account being accessed 
at remote node TORONTO. Note that TORONTO is a logical name. 


3.3.9 DUMP/RECORDS 


Use the DUMP/RECORDS command to display the contents of remote files 
in ASCII, hexadecimal, decimal, or octal representation. The DUMP 
command qualifiers /ALLOCATED and /BLOCKS are not supported in the 
network context. 


Example 


$ DUMP/RECORDS/OCTAL/WORD 
$ File: DALLAS: :DBO: [117,10]CALC.DAT/PRINTER 


This DUMP/RECORDS command dumps the contents of the file 
CALC.DAT, which resides at remote node DALLAS; formats the 
output both in octal words and in character’ strings; and 
queues the output to the system printer at the local node. 


3.3.10 PRINT/REMOTE 


Use the PRINT/REMOTE command to queue files for printing at the remote 
nodes on which they exist. One copy of each file specified is 
printed. You can specify on the same command line files that exist at 
different nodes. If you specify in a PRINT/REMOTE command two or more 
files that reside on the same remote VAX/VMS node, each file is 
entered in the SYSS$PRINT queue as a Separate print job. (Note that 
the PRINT/REMOTE command does not copy the files to the remote node; 
a separate COPY command must be issued if the file does not reside at 
the remote node on which it is to be printed.) 


The /REMOTE qualifier is required in the PRINT command whenever a file 
specification contains a node name. When you specify /REMOTE, you 
cannot specify any other qualifiers for the command. The /REMOTE 
qualifier can appear with the command or after a file specification. 
The PRINT command supplies a default file type of LIS if you omit’ the 
file type from the file specification. 
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Examples 


1. $ PRINT/REMOTE BOSTON: :WORKS: [DECNET.V3]USRGUIDE.MEM,EXP1.FOR 
$ PRINT BOSTON: :WORKS: [DECNET.V3]USRGUIDE.MEM, EXP1. FOR/REMOTE 


Either of the two commands shown above can be entered at node 
TRNTO to queue for printing at node BOSTON the _ files 
USRGUIDE.MEM and EXP1.FOR which reside at node BOSTON. The 
files are entered in the SYSSPRINT queue as separate print 
jobs. 


2. $ COPY REPORT.MEM BOSTON: :*.* 
$ PRINT/REMOTE BOSTON: :REPORT.MEM 


The two commands shown above are entered at node TRNTO to 
cause the file REPORT.MEM located at node TRNTO to be printed 
at remote node BOSTON. The file is copied into the default 
DECnet directory at the remote node and is not deleted after 
printing. 


3. $ COPY REPORT.MEM BOSTON: : LPAO: 


An alternative way of performing the same operation as in 
example 2 above iS to copy the file REPORT.MEM at node TRNTO 

* to the printing device on the remote system. If the printing 
device is spooled (as is usually the case for line printers 
on a VAX/VMS system), then the file will not be sent directly 
to the device, but rather will be temporarily stored on disk, 
entered into the print queue for the device, and deleted 
after it is printed. 


3.3.11 SEARCH 


Use the SEARCH command to search one or more remote files for a 
specified string or strings. 


Example 


$ SEARCH TRNTO::DBA1: [EXP]SUB.DAT,DATA.LIS 
$ String(s): NAME 


The SEARCH command causes the files SUB.DAT and DATA.LIS at 
remote node TRNTO to be searched for all occurrences of the 
character string NAME. The list of all occurrences of NAME 
is printed at the local terminal. 


3.3.12 SORT and MERGE 


Use the SORT command to invoke the VAX-11 Sort Utility. This program 
reorders records in the input file as directed and creates a new 
output file or, optionally, an address file that you can use to access 
the reordered records. 


Use the MERGE command to invoke the VAX-11 Merge Utility, which 
combines two or more sorted files into a single output file that the 
utility program creates. The files to be combined must be similarly 
sorted, but can reside at different VMS nodes. 
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Examples 


l. $ SORT/KEY=(POSITION:1,SIZE:7) - 
$ DENVER: :DB1: [RECS]RNDM.FIL ALPHANM. SRT/KEY= (1, 7) 


This SORT command requests a default alphanumeric sort of the 
records in the file RNDM.FIL at remote node DENVER. The SORT 
program sorts the records on the basis of the contents of the 
first seven characters in each record and writes the sorted 
list into the output file ALPHANM.SRT created in the default 
directory at the local node. 


2. $ MERGE/KEY=(POSITION:1,SIZE:30) - 
$ TRNTO:[PGM]FILE1.SRT, FILE2. SRT/CHECK SEQUENCE —- 
$_MERGEFILE.DAT 


This MERGE command causes two identically sorted files, 
FILE1.SRT and FILE2.SRT, on the directory PGM at remote node 
TRNTO to be merged into another file, MERGEFILE.DAT, created 
in the current default directory at the local node. The 
input file qualifier /CHECK SEQUENCE is specified to ensure 
that the input files are sorted in the correct order. 


3.3.13 SUBMIT/REMOTE 


Use the SUBMIT/REMOTE command to enter command procedure files 
residing on a remote node into the batch job queue for execution at 
the remote node. You can specify on the same command line command 
procedure files located at different remote nodes. If you specify in 
a SUBMIT/REMOTE command two or more files located at the same remote 
VAX/VMS node, each file is entered in the SYSSBATCH queue as a 
separate batch job. (Note that the SUBMIT/REMOTE command does not 
copy the files to the remote node: a separate COPY command must be 
issued if the file does not reside at the remote node where it is _ to 
be executed.) 


The /REMOTE qualifier is required in the SUBMIT command whenever a 
file specification contains a node name. When you specify /REMOTE, 
you cannot specify any other qualifiers for the command. The /REMOTE 
qualifier can appear with the command or after a file specification. 
If you omit the file type from the .file specification, the SUBMIT 
command supplies a default file type of COM. 


Examples 


1. $ SUBMIT/REMOTE BOSTON: : DMA3: [BROWN] JOBS.COM,LISTALL.COM 
$ SUBMIT BOSTON: :DMA3: [BROWN] JOBS.COM, LISTALL.COM/REMOTE 


This SUBMIT/REMOTE command entered at node TRNTO submits’ the 
files JOBS.COM and LISTALL.COM on device DMA3 at remote node 
BOSTON for execution as separate batch jobs. 


2. $ COPY ANALYSIS.COM BOSTON: :*.* 
$ SUBMIT/REMOTE BOSTON: :ANALYSIS.COM 


The two commands shown above are entered at node TRNTO to 
cause the file ANALYSIS.COM residing at node TRNTO to be 
executed at remote node BOSTON. The file is copied into the 
default DECnet directory at the remote node, and is not 
deleted after execution. 
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3.3.14 TYPE 


Use the TYPE command to display the contents of one or more _ remote 
files on the current output device. If you omit the file type in the 
file specification, the TYPE command supplies a default of LIS. 


Examples 


1. $ TYPE TRNTO::DBA1: [DOE]LOGIN.COM 


The TYPE command requests that the file LOGIN.COM in 
directory DOE at remote node TRNTO be displayed at the local 
terminal. 


2. $ TYPE KANSAS: :"STEXT.CMD" 


The TYPE command requests that the file TEXT.CMD on remote 
RSTS/E node KANSAS be displayed at the local terminal. Note 
that you use quotation marks when the file specification 
syntax of the remote node differs from that of VAX/VMS. 


3. $ TYPE TORONTO: :NOTICE. TXT/OUTPUT=TEMP. TXT 


The TYPE command requests that the file NOTICE.TXT at _ the 
remote node designated by the logical name TORONTO be written 
to the specified output file, TEMP.TXT, on the local node 
rather than to SYSSOUTPUT. 


3.4 LEXICAL FUNCTIONS 


DCL command procedure files can include lexical functions that return 
information about remote files. The lexical functions that can be 
used in a network environment are: 


FSFILE ATTRIBUTES (file-spec,item) 
FSPARSE (file-spec[ ,default-spec] [,related-spec] [,field]) 
FSSEARCH (file-spec[ ,stream-id] ) 


Descriptions of the use of these lexical functions in returning 
information on remote files is given below. Complete descriptions of 
these lexical functions appear in the VAX/VMS Guide to Using Command 
Procedures. 


An example of a command procedure that includes all three lexical 
functions appears in Section 3.6.1. 


3.4.1 FSFILE ATTRIBUTES 


Use the FSFILE ATTRIBUTES lexical function in a command procedure to 
return a particular item of attribute information about a specified 
local or remote file. Listed under the description of 
FSFILE ATTRIBUTES in the VAX/VMS Guide to Using Command Procedures are 
the items you can specify in the function (for example, ORG for file 
organization). The file-spec is specified as a string expression, or 
a symbol equated to a string expression; no wild card characters are 
allowed. 
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Example 


$ RFM = FSFILE("KANSAS::SY: [200,2]SALES.CMD","RFM") 


$ SHOW SYMBOL RFM 
RFM = "STM" 


This example returns the record format string of STM (stream) 
for the file SALES.CMD at remote RSTS/E node KANSAS. 


3.4.2 FSPARSE 


Use the FSPARSE lexical function to return a full file specification, 
or a particular field of that specification, for a local or remote 
file. To identify the file in the lexical function, specify a 
file-spec and, optionally, a default-spec and related-spec. These 
arguments are string expressions or symbols equated _ to string 
expressions. 


To obtain a portion of a file specification, specify a field name _ in 


the lexical function. The field names can be any of the following: 
DEVICE, DIRECTORY, NAME, NODE, QUOTED, TYPE, or VERSION. 


Example 
$ SPEC = FSPARSE("DENVER::DB1l: [PROD] RUN.DAT",,,"TYPE") 
$ SHOW SYMBOL SPEC 
SPEC = ".DAT" 


In this example, the FSPARSE lexical function returns’ the 
file type DAT for the file RUN.DAT at remote node DENVER. 


3.4.3 FSSEARCH 


Use the FSSEARCH lexical function to obtain full file specifications 
for local or remote files that match the file-spec given in the 


lexical function. The file-spec, a string expression or _ symbol 
equated to a string expression, can be any valid VAX/VMS file 
specification, and can include null or wild card fields. Each 


consecutive search function returns the next matching file 


specification in sequence. When there are no more resultant strings, 
the null string is returned. 


Example 
SLOOP: 
$ FILESPEC = FSSEARCH("TRNTO: : DBA1: [PROD] *. DAT") 
$ IF FILESPEC .EQS. "" THEN EXIT 


$ GOTO LOOP 


This example causes the directory [PROD] at remote node TRNTO 
to be searched for all files of the type DAT. 


3.5 COMMANDS FOR ACCESSING RECORDS 


You can use DCL commands within command procedures to open and close 
files that reside on remote nodes and to read and write records in 
these files. In command procedure files to be executed during network 
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operations, you can specify all command and file qualifiers for OPEN, 
CLOSE, READ, and WRITE that you would normally use in command 
procedures to access local files. 


3.5.1 OPEN and CLOSE 


Use the OPEN command to open a file for reading or writing at the 
command level. The CLOSE command closes a file that was opened for 
input or output with the OPEN command and deassigns the logical name 
specified when the file was opened. 


The DCL statement OPEN/WRITE creates a file in VFC (variable with 
fixed control) format. If the remote node does not Support VFC 
format, an RMSS$ SUPPORT error will be returned. 


Example 


$ OPEN/READ INPUT FILE TRNTO::DBAO: [COST] INVENTORY. DAT 
SREAD LOOP: = 

$ READ/END OF FILE=ENDIT INPUT FILE NUM 

$ FIRST CHAR=FSEXTRACT(0,1,NUM) 7 

$ WRITE SYSSOUTPUT FIRST CHAR 

$ GOTO READ LOOP 

SENDIT: 2 

$ CLOSE INPUT FILE 


This command procedure opens the file INVENTORY.DAT located 
at remote node TRNTO as an input file and assigns it the 
logical name INPUT FILE. The READ command reads aé_e record 
from the logical file INPUT FILE into the symbol named NUM. 
The next two commands extract the first character from the 
record and write the record to the SYSSOUTPUT device. These 
two steps occur for all records of the file until the 
procedure reaches the end-of-file. At this point, the CLOSE 
command closes the file and deassigns the logical name 
INPUT FILE. 


3.5.2 READ and WRITE 


Use the READ command to read a single record from a specified remote 
input file. Use the WRITE command to write a record to a specified 


output file. 
Example 


1. $ OPEN/WRITE OUTPUT FILE TRNTO: : DBA1: [PGM] PLAN. DAT 
$ WRITE OUTPUT FILE "BEGINNING PHASE 3" 


This WRITE command writes a single line of text to the file 
PLAN.DAT at remote node TRNTO. 


2. $ OPEN/READ INPUT FILE TRNTO: : INVENTORY. DAT 
$ OPEN/WRITE OUTPUT FILE RECEIVE. DAT 


$ READ INPUT FILE DATA_LINE 
$ WRITE OUTPUT FILE DATA _LINE 


The READ command requests data from the file INVENTORY.DAT at 
remote node TRNTO. The WRITE command writes the value of the 
symbol DATA_LINE to the local file RECEIVE.DAT. 
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3.6 COMMAND PROCEDURE EXAMPLES 


The following examples illustrate DCL command procedure files you can 
use in a network environment. 


3.6.1 Command Procedure Using Lexical Functions 


The command procedure shown below, called LISTIDX.COM, employs’ the 
lexical functions FS$PARSE, FSSEARCH, and FSFILE ATTRIBUTES to locate 
indexed files in a directory at a local or remote node. 


LISTIOX.cCOM 


! 
! This command rrocedure disrlays the mames of sll indexed 
! files found in the seecified directors, excluding files 
! with es file tyre of TMF. Fi ois @ file-gree thet can 
! ortionally be used to indicate the directory to be 
! searched. 

! 

FILE = FEPARSECFis*k,.*") 

WRITE SYS#OQUTFUT "A list of indexed files follows .«..° 

WRITE SYS$OUTPUT "* 

$¢Loor?: 

$ NEXT = FESEARCH(FILE) 

$ IF NEXT .E€QS. °" THEN GOTO DONE 

* IF FEPARSECNEXTs ss "TYFE*) .EQS. *.TMF"* THEN GOTO LOOF 

$ IF Fe¢FILEL ATTRIBUTES CNEXT: ORG") .NES. “TOX" THEN GOTO LOOF 

$ WRITE SYSS$QUTFUT NEXT 

$¢ GOTO LOOF 

#DONE% 

$ EXIT 


a th 4 oF 4 eR a Ot 


3.6.2 Command Procedure Using SYSSNET 


The example below illustrates a command procedure, called SHOWBQ.COM, 
that returns batch job status information to its requestor. Note that 
you can use SHOWBQ.COM for task-to-task communication by entering a 
task-spec-string in a TYPE command. For example: 


$ TYPE TRNTO"BROWN JUNE": :"TASK=SHOWBQ" 


In this command procedure, SYSSOUTPUT is equated to SYSSNET in user 
mode to allow the SHOW QUEUE image to communicate over the logical 
link by opening SYSSOUTPUT. When the SHOW QUEUE image exits, the 
temporary definition of SYSSOUTPUT is deleted. In other words, only 
one DCL image can use the logical link as the communication path _ to 
the requestor at the other node. 


I 
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ak 
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SHOWBRQ,.COM 

This command rrocedure returns status information sbout 
Jobs entered in ostenh eueues on the system where it 
executes, It mee be run interactively as 6 command 


Frocedurey BupmMitted as 2 local or remote betcn Jobs oar 
invoked as 6 “remote task" to disrlaey information shout 
another system. For e@xemrle$ 


$ @SHOWRQ 

$ SUBMIT SHOWBRQ 

$ SUBMIT/REMOTE node? i SHOWRQ 
$ TYFE nodes: *TASK=SHOWBQ" 


IF F¢MODE() .EQS. “NETWORKS THEN GOTO NET 
SHOW QUEUE/BATCH/BRIEF/ALL 

f EXIT 
$NET: 


$ HEFINE/USER SYSSOUTPUT SYS#NET 

$ SHOW QUEUE/BATCH/BRIEF/ALL 

$ FURGE/KEEFP=1 SYS¢LOGIN? SHOWRQ.LOG 
$ EXIT 


3.7 DISPLAY OF ERROR MESSAGES IN NETWORK ENVIRONMENT ~ 


When you enter a DCL command to perform a network file operation 


that 


does not complete successfully, one or more error messages are written 
to SYSSERROR. The following sequence of error messages is typical: 


Network-specific RMS completion codes and their corresponding 


An error message generated by the DCL command interpreter 


A primary error message generated by the VAX-11 Record 
Management Facility (RMS) 


An optional secondary error message associated with the 
primary RMS error (from a facility involved in the network 
file operation) 


message 


text are described in Section 4.3. 


Examples 

1 $ COPY BOSTON: :DBB2: [TEST]RSLT.DAT *,.* 
$COPY-E-CLOSEIN, error closing _BOSTON: : DBB2: [TEST] RSLT.DAT; 1 
as input 
-RMS-E-CRC, network DAP level CRC check failed 
A file-level CRC checksum error was detected when the input 
file RSLT.DAT was closed. Error messages generated by the 
DCL command interpreter and the RMS facility are displayed on 
the terminal. 

2. $ COPY INDEX.DAT BANGOR: : TEMP. DAT 


tCOPY-E-OPENOUT, error opening _BANGOR::TEMP.DAT; as output 
-~RMS-F-SUPPORT, network operation not supported 
-FAL-F-ORG, file organization field rejected 


An attempt to copy the file INDEX.DAT to TEMP.DAT at remote 
node BANGOR failed because the latter does not support 
indexed files. The following generated error messages: the 
DCL command interpreter, the RMS facility, and the remote 
File Access Listener (FAL) file server utility. 
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VAX/VMS provides an efficient and flexible means for accessing remote 
files in a network environment. Using VAX-11 RMS facilities, you can 
perform file-handling operations on entire files or individual records 
via programmed calls in VAX-11 MACRO or in one of the higher-level 
languages supported over the network. The programming procedures 
described in this chapter use standard VAX-11 RMS and higher-level 
language I/O calls to: 


e Create and delete remote files 
e Process existing remote files 


e Read, write, update, or delete individual records within 
remote files 


e Perform miscellaneous operations on a file such as rewinding a 
record stream, displaying or modifying file attributes, or 
extending the size of a file 


This chapter describes the general procedures for accessing remote 
files using VAX-11 MACRO. Specifically, it discusses network access 
at the RMS level, network restrictions on file access, network error 
reporting, and the use of higher-level and MACRO languages in 
accessing remote files. The information and examples presented herein 
also provide the necessary framework for the discussion of remote file 
access found in each higher-level language user guide. You should 
also be familiar with the VAX-11 Record Management Services Reference 
Manual. 


4.1 ACCESSING THE NETWORK AT THE RMS LEVEL 


Conceptually, accessing the network at the RMS level is the same as 
accessing RMS directly for local file-handling operations. To access 
remote files on a VAX/VMS node, use either DCL commands or VAX-11 RMS 
service calls along with a standard VAX/VMS file specification that 
includes a node name. 


Because higher-level language 1/0 calls are translated into VAX-11 RMS 
calls, the term "RMS' service calls" in this chapter includes these 
language-specific calls. 


For remote file processing, VAX-11 RMS integrates the network software 
necessary to translate standard RMS service calls into the appropriate 
system service calls, thereby providing a transparent user interface 
to the network. 


When you issue an RMS service call with a file specification that 


specifies a remote node, VAX-11 RMS communicates the access request 
via the Data Access Protocol (DAP) to the File Access Listener (FAL) 
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task at the remote node. Each DECnet node that supports remote file 
access has a FAL task that receives and processes remote file access 
requests. FAL translates the calls of the accessing process’ into 
system-specific file-handling calls to perform the desired operations 
on files at that node. Figure 4-1 illustrates this entire process as 
it relates to file access processing in both DCL and VAX-11 RMS. 


The way you access individual files on a remote system depends on the 
source language of the accessing program and on the file system that 
resides on the remote node. The next section of this chapter 
discusses these considerations as they pertain to programming remote 
file-handling applications. 


Local Node TRNTO:: 


COPY*.* BOSTON::”*.* 
(DCL Command) 


as 


LL 


wy | vax/vms__ | 


DCL Interpreter | 





Remote Node | 
| | BOSTON:: 


Process So asi oe ee eee ee 
Using | avs | | VAX/VMS | 
Remote Processing | = ——-- 5 
File Access | | DECnet-VAX 





Software 
| | | ——— 


| DECnet-VAX | File 
Software FAL | | System 


File | | | | 
System 





ZK-839-82 


Figure 4-1: Remote File Access (DCL and RMS) 


4.2 VAX-11 NETWORK FILE ACCESS RESTRICTIONS 


VAX/VMS supports transparent remote file and record access at the 
programming level, including the use of most VAX-11 RMS file and 
record operations normally available to the VAX/VMS- programmer. 
Within the context of these operations, however, certain restrictions 
apply to the method of file and record access you can use. 
Specifically, each programming language specifies the way you can 
access individual files. In addition, the way you access a file may 
be restricted further by the type of file operations supported by the 
remote file system. The user guide for each higher-level language 
describes those restrictions that apply for file access operations 
performed in that language. VAX-11 RMS restrictions are listed below 
and in Section 4.5.3. 


Table 4-1 summarizes the file organizations and record formats’ that 
VAX-11 RMS defines for network operations on remote files from a local 
VAX/VMS node. Table 4-2 shows the RMS record access methods and block 
I/O modes for such network operations. 
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Table 4-1: VAX-11 RMS File and Record Characteristics 
for Network Operations 













File 
Organization 


Record Format 


PFIXL VAR 2 VFC3 sTm4 | stucr> | | STMLES | 










Sequential 






Relative 


Indexed 





1 - FIX: Fixed-length record format 
2 - VAR: Variable-length record format 
3 ~ VFC: Variable-length with fixed-length coneter record format 
4 - STM: Stream format with record terminator set of 
LF, FF, VT, and CRLF 
5 - STMCR: Stream format with record terminator set of CR 
6 - STMLF: Stream format with record terminator set of LF 
7 - NA: Not applicable 


Table 4-2: VAX-11 RMS Access Modes for Network Operations 


Record Access Mode Block I/O Mode 


Sequen- Random by: Sequen- | Random by 
tial Relative Key | Record tial Virtual 
Record Value File 
Number Address 
BEE : 


Block 
1. For fixed-length records only 









File 
Organization 















Number 









Sequential 










Relative 


Indexed 





4.3  VAX-11 RMS NETWORK ERROR REPORTING 


For both local and remote file operations, VAX-11 RMS reports’ the 
success or failure of an operation by returning an RMS completion 
code. This primary status code is returned in both Register 0 (RO) 
and the completion status code field (STS) of the file access block 
(FAB) or record access block (RAB) specified in the original RMS 
service call. In addition, some RMS completion codes have secondary 
status information associated with them. This information is returned 
in the status value field (STV) of the FAB or RAB in the form of 
either another status code (usually from a different facility) or a 
value that qualifies. the primary status code (such as a count). The 
RMS completion codes are listed in the VAX-11. Record Management 
Services Reference Manual. 


When an RMS service call is issued for a network file operation, RMS 
enters into a dialog with the FAL server at the destination node, in 
order to perform the desired operation through the file system in use 
at that node. These cooperating processes communicate using the Data 
Access Protocol (DAP) to transfer data and to pass control and status 
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information to each other. (The DECnet DIGITAL Network Architecture 


=e eee 


To promote network transparency, VAX-11 RMS attempts to map the status 
information returned by FAL into the RMS completion code that would be 
returned if the file had been accessed locally. It is not possible, 
however, to map every DAP status code directly into an RMS code 
applicable to local file access, particularly if the remote system 
does not use VAX-11 RMS to manage its files. Moreover, certain error 
conditions occur only in a network context. To handle these cases, 
several network-specific completion codes have been defined. These 
codes are summarized in Table 4-3. 


Table 4-3: Network-Specific RMS Completion Codes 


RMS$_ACS error in access control string 


Indicates that the format of the access’ control 
string used in the file specification is 
invalid. 


RMS$_BUG_DAP Data Access Protocol error detected; DAP code = 
"xXxXxXXxXxx'! 


Indicates that the operation failed because of a 
protocol error detected by either RMS or FAL. 
VAX-11 RMS returns this code in the STS field 
and a companion DAP code in the STV field. Note 
that a reproducible RMS$ BUG DAP error indicates 
a DECnet software error condition that should be 
reported to DIGITAL in a Software Performance 
Report. However, a nonreproducible RMS$ BUG DAP 
error, especially one that occurs on a 
communications line that has had RMS$ CRC errors 
reported, normally indicates a hardware 
malfunction. 


RMS$_ CRC network DAP level CRC check failed 


Signals that file-level cyclic redundancy check 
(CRC) checksums computed by RMS and FAL did not 
match when compared at file close, thus 
indicating that the file is corrupted in some 
manner. This condition is caused usually by a 
hardware problem; if it occurs’ repeatedly, 
check the communications hardware. You should 
retry the file access. If DECnet event logging 
is enabled, you can set the Event Logger (EVL) 
to count CRC errors and display CRC error 
messages. For a connection between two VAX/VMS 
nodes, both RMS and FAL will independently log 
the event on their systems. (Event logging is 
described in the DECnet-VAX System Manager's 
Guide.) 
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Table 4-3 (Cont.): Network-Specific RMS Completion Codes 


RMS$ CRE STM file was created in stream format 


Indicates that RMS has created the file in 
stream format with embedded carriage control 
because the format and carriage control 
specified in the RMS SCREATE call is not 
supported by the remote node. 


RMS$_FT™ network file transfer mode precludes operation 
(SQO set) 


Indicates that RMS could not perform the 
requested operation because DAP file transfer 
mode was in effect. For network file access, 
setting the SQO bit in the FOP field of the FAB 
selects DAP file transfer mode. In this mode, 
the software blocks data records together for 
transmission over the network. This blocking 
increases data throughput and reduces CPU 
overhead. However, selection of this mode 
limits data transfers to one direction: either 
transmits using $PUT or SWRITE or receives using 
SGET or SREAD. It also disallows' other 
VAX-11 RMS record operations for the logical 
link until the record stream is terminated, via 
either SDISCONNECT or S$CLOSE. Refer to Section 
4.5.3 for additional information. 


RMS$ NETFAIL network operation failed at remote node 


Indicates that the requested operation could not 
be performed by the file system at the remote 
node. The STV field contains a FAL status code 
that describes the failure in the context of the 
remote system. 


RMS$_NET network operation failed at remote node; DAP 
code = 'xxxxxxxx' 


Indicates the same condition as the RMS$_NETFAIL 
code (see above) except that the accompanying 
DAP status code cannot be translated into a_ FAL 
status code. RMS$ NET is returned in the STS 
field and the DAP code in the STV field. 


RMS$_NOD error in node name 


Indicates that the node name portion of the file 
specification string has incorrect syntax. 


RMS$_QUO error in quoted string 
Indicates that the quoted string portion of the 


file specification (either the foreign-file-spec 
or task-spec string) has incorrect syntax. 
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Table 4-3 (Cont.): Network-Specific RMS Completion Codes 


RMS$_SUPPORT network operation not supported 


Indicates that VAX-1l1 RMS rejected the request 
because the operation requested is not supported 
over the network. The STV field contains either 
another RMS completion code or a FAL status 
code, depending on whether VAX-11 RMS at the 
local node or FAL at the remote node could not 
support the request. 


RMS$_SUP network operation not supported; DAP code = 
"XXXXXXxx! 


Indicates the same condition as the RMSS$ SUPPORT 
code except that the accompanying DAP status 
code cannot be translated into a FAL status 
code. RMSS SUP is returned in the STS field and 
the DAP code in the STV field. 





In general, RMS completion codes returned in response to network 
operations fall into one of the following categories: 


The operation was successful. 
The operation was not supported by the network. 
The operation was attempted but failed. 


An end-to-end file-level cyclic redundancy check (CRC) 
failed. 


A DAP error was detected. 


VAX-11 RMS reports status for each of these categories as follows: 


l. 


Successful completion of a network operation is reported 
using the same RMS completion codes as those used to report 
the status of a local file operation. The RMS ‘success 
completion code RMS$_ NORMAL or an alternate success 
completion code (for example, RMSS CRE STM) is returned in 
the STS field. Depending on which RMS code is used, the STV 
field may or may not contain auxiliary information. 


If an operation is not supported in a network context, the 
failure of the request is reported as either an RMS$ SUPPORT 
or an RMSS$ SUP error. Most frequently returned is the 
RMS$ SUPPORT error, which has an associated secondary status 
code in the STV field. This secondary code is either another 
RMS completion code or a FAL status code, depending on 
whether RMS at the local node or FAL at the remote node could 
not support the request. The RMSS$S_SUP completion code is 
used only when RMS cannot map the DAP status code returned by 
FAL into a meaningful FAL status code. For RMSS$ SUP, the 
uninterpreted DAP status code is returned in the STV field. 


An operation supported over the network may fail while being 
processed by either the local or the remote file system. If 
the failure occurs at the local node, an appropriate RMS 
completion code is returned. (Examples of codes’ returned 
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when errors are detected locally by RMS are RMSS ACS, 
RMS$_FTM, RMSS$ NOD, and RMS$ QUO.) On the other hand, when a 
file operation fails while being processed by the file system 
at the remote node, RMS attempts to map the DAP status code 
generated by FAL into a corresponding RMS completion code. 
This mapping normally succeeds, but if an appropriate match 
cannot be found (because the error is specific to the remote 
file system), one of the following is returned to the user: 
RMSS$S NETFAIL or RMSS$ NET. Both of these codes indicate that 
the failure occurred at the remote system, but differ in the 
format of the contents of the STV field. If the DAP status 
code can be transformed into a FAL status code, RMSS$ NETFAIL 
is returned with the FAL status code that describes’ the 
failure in terms of the remote file system. Otherwise, 
RMSS$S NET is returned with the uninterpreted DAP status code 
in the STV field. 


4. If a file-level CRC check failure occurs, the failure is 
Signaled by means of the RMS$ CRC completion code for the 
SCLOSE service call. There is no secondary status 
information associated with this error condition. When a 
remote file is opened (or created) through VAX-11 RMS on a 
VAX/VMS node, RMS determines whether the remote FAL supports 
the DAP option of performing an end-to-end CRC check on _ the 
data accessed in the file. If FAL supports this option, then 
RMS and FAL agree to compute independently a cumulative CRC 
checksum based on the records (or blocks) each sends and/or 
receives. As part of the close operation, FAL compares’ the 
two checksums and reports status back to RMS. Thus an 
RMSS$ CRC error alerts the user that the file has been 
corrupted during transfer. Repeated reports of this error 
for the same line indicate the possibility of a hardware 
failure. 


5. During the exchange of DAP messages, should either node 
detect a protocol violation, RMS aborts the operation and 
returns the RMS$ BUG DAP error code with a corresponding DAP 
Status code in the STV field. A_ protocol violation is 
detected, for example, when a syntax check of a DAP message 
fails or RMS and FAL get out of synchronization (that is, a 
DAP message is received that is inappropriate for the current 
state). 


4.4 HIGHER-LEVEL LANGUAGE REMOTE FILE ACCESS 


Regardless of the programming language used, you access remote files 
in exactly the same way that you would access local files. To 
illustrate the way you access remote files, Example 4-1 provides a 
simple FORTRAN program to transfer a remote file on node TRNTO to the 
line printer on node BOSTON, 


REMOTE FILE ACCESS USING RMS 


Example 4-1: FORTRAN Remote File Access Program 


FROGRAM TRANSFER. FOR 


C 
C This Frosgram crestes &@ seauential file with varisble length 
C records from = seauentiel ineut file, The ainseut end outeut 
C files ere identified oe the logicael names SRC end 5ST» 
C resrectivels. For exsmeles to rrint e file on &@ remote system 
C that resides an another system? 
Ct $ TEFINE SRC TRNTO? 3 USERS CSTOCKROOM.FAFPERJINVENTORY. DAT 
C $ DEFINE DST BOSTONISLEAO: 
C €¢ RUN TRANSFER 
C 
CHARACTER BUFFER¥122 
C 
1606 FORMAT (QA) 
200 FORMAT ¢A) 
C 
C Oren the inreut and outrut files, 
Cc 
OPEN CUNIT=1»NAME=‘“SRC’»TYPE=‘OL0’ »sACCESS="SEQUENTIAL? » 
1 FORM=‘’FORMATTED’) 
OREN CUNIT=2>NAME=‘UST’ »TYPE=’NEW’ »ACCESS=* SEQUENTIAL” » 
lL FORM=‘FORMATTED’ sCARRIAGECONTROL=‘LIST( + 
2 RECORITYPE=’“VARTAELE“} 
C 
C Transfer recards until end-of-file ar other error condition. 
C 
190 READ CisilOOs END=20,;ERR=26) NCHARsBUPFERC I NCHAR) 
WRITE €2°200) BUFFERCENCHAR) 
GOTO 10 
C 
C Close the ineut and auteut files, 
Cc 
20 CLOSE CUNIT=23) 
CLOSE CUNIT=1) 
ENT 


The program in Example 4-1 uses standard I/O calls to transfer the 
file from one device to another. Initially, two DCL commands are used 
to define logical names for the files involved in the transfer. Note 
that you use the standard VAX/VMS file specification with a remote 
node name to specify the source and destination files. (If the remote 
node is other than VAX/VMS, the format of the file specification may 
differ.) The FORTRAN program must open the files. When opening a 
file, you must specify a unit over which the operation is to be 
performed. In this example, the access mode is sequential. Standard 
read and write calls serve to move the data from the source to the 
destination file. After all the records have been transferred, the 
program closes the channels, thereby terminating network operations. 
These operations are similar for applications in the other 
higher-level languages supported under VAX/VMS. 


4.5 MACRO REMOTE FILE ACCESS 


VAX/VMS provides a transparent programming interface for remote file 
access uSing VAX-11l MACRO. The following sections describe the use of 
VAX-11 RMS calls for VAX-11 MACRO remote file access, discuss network 
error mapping considerations, and present several examples of programs 
written in VAX-11 MACRO that illustrate the use of these calls. 
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4.5.1 Using VAX-11 RMS Service Calls 


In general, you follow four steps when developing a MACRO remote file 
access application: . 


1. Initialize a set of data structures that VAX-ll RMS uses for 
processing RMS service requests (in the same way as for local 
MACRO program development) 


2. Open the files for processing and establish a record stream 
for each file 


3. Issue the appropriate RMS service calls to perform the actual 
file-handling operations 


4. Disconnect the record streams and close the files after file 
processing has been completed 


4.5.1.1 File Access Blocks (FABsS) and Record Access Blocks (RABs) - 
These serve as the discrete data structures that VAX-1l11 RMS uses to 
process service requests. In general, you should allocate one FAB for 
every file your program will open and one RAB per file to establish a 
record stream. The parameters associated with these control blocks 
define the exact characteristics of the files designated for 
processing. One of these parameters is the network file 
specification. Through the use of either a logical name or a complete 
file specification string, you designate the file that you want to 
access. 


4.5.1.2 S$OPEN and S$CONNECT - Once you have defined the user control 
blocks, you can then open the files and establish a record stream to 
each one. Use the RMS service calls SOPEN and $CONNECT in conjunction 
with the FAB and RAB to prepare for file processing. When you issue 
the SOPEN call, you effectively establish a logical link connection 
with the remote FAL. 


When the file is open, you can perform file and record operations 
through the use of standard RMS service calls such as $GET, $PUT, and 
SUPDATE. For added flexibility, VAX/VMS supports block I/O RMS calls 
for writing and reading blocks of data to and from remote files. 


4.5.1.3 S$DISCONNECT and $CLOSE - Finally, after processing completes, 
you should disconnect all record streams and close all files. First, 
use the S$DISCONNECT call to disconnect the RAB, and then use the 
SCLOSE call to close the FAB, thereby signaling the completion of 
network operations. This procedure terminates the logical link in an 
orderly fashion. Note that the S$CLOSE macroinstruction will 
automatically disconnect the record stream for the RAB associated with 
the specified FAB. 


4.5.2 VAX-11 RMS Service Call Summary 


Table 4-4 summarizes the VAX-11 RMS service calls you can use _ for 
MACRO remote access operations: file processing, record processing, 
block I/O processing, and file specification processing. This table 
lists calls supported for file operations between two VAX/VMS nodes 
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over the network. The following operations are not supported in this 
environment: SENTER, SNXTVOL, SREMOVE, and SRENAME. (If one of these 
operations is requested by a VAX/VMS node communicating via DECnet 
with another VAX/VMS node, the RMS$ SUPPORT (network operation not 
Supported) error message is returned.) 


Appendix B describes network considerations relating to the use of 
VAX-11 RMS control blocks associated with the calls listed in Table 
4-4. For a complete explanation of the syntax and parameters for each 


AD 


Table 4-4: VAX-11 RMS Service Calls for Run-time 
Remote File Access 


Name of MACRO Description of Service 


File Processing 


SCLOSE Closes an open file, optionally 
providing for file disposition, 
and terminates file processing 


SCREATE Creates a new file with the 
attributes specified, opens it, 
and initiates file processing 


SDISPLAY Returns the attributes of a file 
to the user program 


SERASE Deletes a closed file and 
removes its directory entry 


SEXTEND Increases space allocated to an 
open disk file 


SOPEN Opens an existing file, 
optionally returns its file 
attributes, and initiates file 
processing 


Record Processing 


SCONNECT Establishes a record stream by 
associating a RAB with an open 
file 


SDELETE Deletes a record from a relative 
or indexed file 


SDISCONNECT Terminates a record stream by 
disconnecting a RAB from an open 
file 


SFIND Locates and positions to. the 
specified record in the file 


SFLUSH Forces buffered records and 
modified file attributes to be 
written to a file 





(continued on next page) 
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Table 4-4 (Cont.): VAX-11 RMS Service Calls for Run-time 
Remote File Access 


Name of MACRO Description of Service 


SFREE 






Unlocks all records previously 
locked by the record stream 










SGET Retrieves a record from a file 







SPUT Writes a record to a file 


Unlocks a record specified by 
its record file address 


SRELEASE 





Positions to the first record or 
block of a file 


SREWIND 





STRUNCATE Truncates a sequential file 















SUPDATE Modifies a record ina file 





SWAIT Awaits the completion of | an 


asynchronous record operation 


Block I/O Processing 





SREAD Reads data in block I/O mode 






SSPACE Positions forward or backward in 


a file to a block boundary 





SWRITE Writes data in block I/O mode 





File Specification Processing 









SPARSE 





Parses a file specification 





SSEARCH Searches a directory for the 
next file name that matches the 
file specification template 


provided 


4.5.3 VAX-11 RMS Programming Notes and Restrictions 


This section discusses programming topics related to the network of 
interest primarily to the MACRO programmer. Restrictions on the use 
of the VAX-11 RMS interface in a network environment are also 
presented. Refer to Appendix B for additional information on the use 
of RMS control blocks. 


4.5.3.1 Name Block - The DID, DVI, and FID fields of the Name Block 
(SNAM) are not supported for remote file access; these fields are not 
used as input and are zeroed on output. If you set the NAM bit in the 
file-processing options (FOP) field of the FAB to request "open by NAM 
block," this option will be ignored and the open will proceed based on 
the other fields of the SFAB and $NAM blocks. 


REMOTE FILE ACCESS USING RMS 


4.5.3.2 File Specification Processing - Using the RMS SPARSE service 
call to parse a file specification that contains a node name does not 
incur any additional overhead in a network context. VAX-11 RMS 
parses/merges the primary, default, and related file specification 
strings into an expanded name string without invoking a remote FAL 
server. Because the file parse is performed locally, the following 
control block fields are affected on output: 


e In the expanded name string (ESA/ESL) of the Name Block, a 
logical device name is returned without being translated if it 
was encountered after a node name was found during the file 
parse operation, and process default device and directory name 
strings are not applied. 


e In the file name status field (FNB) of the Name Block, status 
bits are not valid if the quoted string format of a file 
specification is used. 


e The device characteristics fields (DEV and SDC) of the FAB are 
not updated to reflect the actual characteristics of the 
remote device. 


In contrast to SPARSE, execution of the RMS service call SSEARCH will 
cause a logical link to be created to communicate with a remote FAL 
server to perform the directory search function. Repeated calls to 
SSEARCH using the same FAB, however, will cause RMS to use the same 
logical link to FAL until the’ search sequence is complete. 
Furthermore, execution of an SOPEN, S$CREATE, or SERASE call following 
a SSEARCH call will cause VAX-11 RMS to establish a new logical link 
with FAL to perform the file access operation. 


4.5.3.3 FOP File Disposition Options on Close - Three options of the 
FOP field of the FAB that affect the disposition of the remote file on 
close require that you supply a resultant name string via the Name 
Block (SNAM) as input to the S$CLOSE service. The options are: 


e DLT to delete the file at the remote node. 


e SCF to submit the command file for execution at the remote 
node. You may. also specify that the file be deleted after 
execution by setting both the SCF and DLT bits. 


e SPL to print one copy of the file at the remote node. You may 
also specify that the file be deleted after it is printed by 
setting both the SPL and DLT bits. 


These options may be requested at either open or close time, but they 
are performed as part of the close operation. The resultant string 
must be the same one received by specifying the Name Block as input to 
the SCREATE or SOPEN calls. If you specified one or more of the FOP 
options previously discussed and you receive a VAX-11 RMS completion 
code of RMS$ SUPPORT (network operation not supported) on $CLOSE, it 
means that the file was closed at the (ROR TVARLVES) target node, but 
none of the options were performed. 


4.5.3.4 FOP Option for Increasing File Transfer Throughput — The Data 
Access Protocol used by VAX-11 RMS and its partner FAL defines two 
major file access modes: DAP file transfer mode (FTM) and DAP record 
access mode (RAM). VAX-11 RMS must tranSlate each user-specified 
access method (for example, sequential, random, block I/0) into one of 
these DAP access modes in order to perform remote file access 
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operations. VAX/VMS Supports both DAP file access modes, whereas most 
DECnet implementations other than VAX/VMS support only FTM. 


FTM is designed to speed up the most common network operation: 
copying files. FTM allows VAX-11 RMS to exchange fewer DAP messages 
with the remote FAL than does RAM when transferring a file. FTM also 
permits data records to be blocked together for transmission, thereby 
potentially reducing the number of QIO system service calls required 
to move the data. The combined effect is that data throughput 
increases as the average record size of the file decreases. A side 
benefit is that this lessens operating system overhead as compared 
with RAM. 


Although FTM offers efficiency, it is restrictive. It requires that 
the file be accessed sequentially (by records or blocks) and that the 
data be moved in one direction (either sent to or retrieved from the 
file). Thus once the record stream is established via a SCONNECT 
call, only S$GET/SREAD or SPUT/SWRITE requests are permitted until the 
record stream is terminated via a S$DISCONNECT or a SCLOSE call. If 
you attempt to mix S$GET/S$PUT or S$READ/SWRITE requests or to issue 
other RMS service calls (such as S$DISPLAY, SEXTEND, SFIND, or 
SUPDATE), VAX-11 RMS will return an RMSS FTM error. 


In contrast, RAM is designed to provide a wide range of functions. 
RAM supports both sequential and random access (by records or blocks), 
numerous record operations such as S$FREE and SUPDATE, and dynamic 
switching of access modes. RAM is also useful for performing 
intermixed $GET/SPUT operations to a bidirectional unit record device. 
such aS a remote terminal or a remote task. However, RAM offers 
flexibility at the expense of efficiency. Each VAX-11 RMS~ service 
call results in an exchange of DAP messages with the remote FAL. Data 
messages cannot be blocked with each other (even when the file is 
accessed sequentially) because RAM requires that FAL acknowledge the 
completion of each file operation before the next one can be 
requested. 


When you open or create a remote file, VAX-11 RMS examines the SQO 
(sequential-only) bit in the FOP field of the FAB to determine whether 
to enter FTM or RAM. If the SQO bit is set, VAX-1l1 RMS selects FTM, 
and you are limited to reading or writing data in a sequential manner. 
If the SQO bit is not set, RMS selects RAM unless the remote FAL 
supports only FTM. If this is the case, then RMS overrides your SQO 
request and enters FTM. Consequently, if you write a program in 
VAX-11 MACRO either to open a remote file and sequentially read data 
or to create a remote file and sequentially write data, it is 
recommended that you select the sequential-only FOP option. This 
option will improve data throughput for transfers between VAX/VMS 
nodes. Where the remote partner is other than VAX/VMS, the SQO option 
will have an effect only if the remote node supports both FTM and RAM. 


4.5.3.5 File Sharing - File sharing between VAX/VMS nodes is 
supported over the network. Different programs can open the same 
remote file for shared access through use of the file sharing 
(FABSB SHR) field of the FAB. Within a single program, however, only 
one record stream can be active for each open remote file. You cannot 
set the FABSV MSE (multistream access enabled) bit of the FABSB SHR 
field and then issue multiple $CONNECT calls for the same file. You 
may, however, reestablish a record stream by issuing a $CONNECT after 
a disconnect operation has been performed without closing and 
reopening the file. 
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4.5.3.6 Restriction on Access to Files on Magnetic Tape -— DECnet-VAX 
does not support access to magnetic tape files located on a remote 
VAX/VMS system. This restriction exists because FAL is not able to 
mount a magnetic tape volume in order to gain access to it. 


4.5.3.7 Task-to-Task Communication - When writing a program to 
communicate with a remote task, you may treat that remote task as 
though it were a unit record device, having characteristics similar to 
those of a VAX/VMS mailbox. The information returned in the device 
characteristics field (DEV) of the FAB block reflects this 
orientation. As a result, Sequential S$GET/SPUT requests are 
appropriate for exchanging data with a remote task, whereas random 
access requests are not. 


The Data Access Protocol is not used for task-to-task communication. 
Consequently, the sequential-only (SQ0O) option in the FOP field of the 
FAB has no effect on data throughput. Each $GET/SPUT request results 
in a QIO system service request to receive or transmit data. 
Furthermore, if one task breaks the logical link, its partner task 
will receive an RMSS$ EOF (end-of-file) error in response to an 
outstanding SGET request. Breaking the link is analogous to pressing 
CTRL/Z on a terminal to indicate an end-of-file condition. In 
response to an outstanding $PUT request, the partner task will receive 
an RMS$ SYS (system QIO directive) error. 


4.5.4 MACRO Programming Examples 


The following examples illustrate the use of VAX-11 RMS service calls 
in MACRO programs that process files on remote nodes. For a general 
discussion of the use of VAX~11 RMS at the local node, refer to the 
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4.5.4.1 MACRO Remote File Transfer Example - Example 4-2 illustrates 
the VAX-11 MACRO counterpart to the VAX-11 FORTRAN remote file 
transfer program in Example 4-1. 
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Example 4-2: RMS File Transfer Program 


eTITLE CREATESEQR - CREATE SEQUENTIAL FILE 
*IDENT /¥OO1/ 


This rrogram creates @ seauential file with variable length records from 
a sequential inreut file. The ineut and outeut files are identified bs the 
losgicel mames SRC and DIST» resrectively., For exemeles to create a file on 
one mode from a file residing on another mode: 


$ DEFINE SRC TRNTOS USERS CSTOCKROOM,FAFERJINVENTORY. DAT 
$ DEFINE OST BOSTON? {TEMPE CARCHIVEJINVENTORY. GAT 
$ RUN CREATESERQ 


“O> “> Sah se sr sem am “a> Sem “cr 


SCOR ORR ORK OKO RRR OK KOK OR KR EK RK RK KK KK KA KK RRR KAR KK EK ERK 


*+SETTL Control block end buffer storage 
*FPSECT [ATA NOEXE» LONG 


3 
+ Tefine the source file FAR and RAB control blocks. 
3 
$ 


SRC_UFAB? 
$F AR FACH“GETS:- » File access for GET only 
FOF=<SQ0>.- > Reauest TAP file transfer mode 
FNM=<SRC> ' Name of inrut file 
SRC_RARB?: 
$RAB FAR=SRC_UFAE:- Address of associated FAB 
RAC=SEQs- Seavential record access 


Buffer address 
Buffer size 


UBF=BUFFER »- 
USZ=BUFFER SIZE 


=> “> “er see 


3 
> Ttefine the destination file FAB and RAB control blocks, 


3 
RSTUFAR? 
$FAR FACH<FUT Ss - ' File secess for FUT only 
FOF=<SQ0>y- *# Reauest DAP file transfer mode 
FNM=<0ST Ss - + Name of ocutrut file 
ORG=SEQ,- + Sequential file organization 
RFM=VARs— i Variable record format 
RATH<CR> * Imelied carriage control 
USTURAB: 
$RAB FABR=R=RSTUFAERs - » AGGress of associated FAR 
RAC=SEQs- > Seauentiel record access 
REF=BUFFER ¢ Buffer address 


; 
s Allocate buffer to be the size of the largest record thet will be read. 
; 

BUFFER: .BLKB 132 > Buffer for ineut and outeut 
BUFFER LSIZE=.-BUFFER + Buffer size 


FOO OOOO OOOO OOK RK OR KK KEK KK KK KKK 


»+SBTTL Mainline 
»PSECT CORE NOWRT» BYTE 


Stert of rrograms Fut FAB and RAR addresses in registers for efficiency, 


=> sap “ae 


Entry roint 

Get aeddiess of inrut FAB 
Get address of inrut RAB 
Get address of outeut FAR 
Get eddress of outrut RAB 


*+ENTRY CREATESEQ? “M<> 
MOVAB W°SRC_FABSRS 
MOVAB W°SRC_ RAB: R7 
MOVAB W°DST.FAB SKS 
MOVAR WTLDSTURABRs RP 


<> “SP “a> “e> ~or 
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; 

$ Oren the source and destination files. 

; 
$OPEN FABERS 3 
ELEC RO,EXIT 3 
$CONNECT RABR=R7 ; 
BLEC ROvEXIT ; 
$CREATE FAR=KS ; 
BLEC ROVEXIT ; 
$CONNECT RABR=R9 ; 
BLBC ROsEXIT ; 

3 

+ Transfer records until end-of-file is 

5 

LOOF $ $GET RAB=R7 , 
BLEC RO»sERROR ; 
MOVW RABSWURSZOR7)s- , 

RABSWURSZCRD) ; 

$F UT RAB=R9 ; 
BLEC ROvsERROR ; 
BRE LOOF ; 

ERROR? CMFL RO,» #tRMS$ EOF ; 
BNEQ EXIT ; 

5 

* Close the source and destination files. 

5 

’ Note that a $0ISCONNECT call is not reavired -rior to closing @ 

+ because the $CLOSE call rerforms en 

; 
$CLOSE FAB=R8 ; 
BLEC ROFEXIT ; 
$#CLOSE FAB=k6 ; 

3 

§ Exit to VMS with RMS completion code in 

>’ failure of rrosgram execution, 

; 

EXIT? €EXIT.S RO ; 
END CREATESEQ ; 


Qeen inreut file 
Branch om féeilure 
Connmect insut recard 
Eranch on feilure 
Create outrut file 
Branch on failure 
Connmect outrut record 
Branch om failure 


stream 


etream 


encountered, 


Read mext record from inrut file 
Branch on failure 
Cory length of recard 
read to outrut RAB 
Write record to outrut file 


Kranch om failure 


Just 


Frocess mext record 
Was it an end-of-file? 
Eranch if not 


file 


imrlied disconmect of the record stream. 


Close gutrut file 
Branch on feilure 
Close inrut file 


RO to sisinal success 


code in k9 
of Frogrem 


Exit with RMS comrletion 
Srecify starting address 


REMOTE FILE ACCESS USING RMS 


4.5.4.2 VAX-11 MACRO Remote File Spooling Example - Example 
spools a sequential file to the printer on the remote node. 


Example 4-3: RMS Spool File Program 


*+TITLE SFOOQL - FRINT AND DELETE FILE 
*TITLE /VOO1/ 


This Frogram srools one cory of s file srecified by the losdicael name 
NST to the rrinter at the remote node where it resides. After neins 
Frinted,s the file is deleted. For examrle} 


$¢ DEFINE DST "BOSTON DEMO NETWORK" "SiC. TESTIPRINTME. DATS 
$ RUN SFOOL 


“Ch WED Re Ser ED ED > sae 


9 KOR KR KKK KK RK KK KK RRR KKK KK KKK RK RK KK RK EK KK KK EKER KK KKK KOR RK KK RK KKK KR KER 


*SETTL Comtrol block and auffer storage 
*FSECT DATA NOEXE» LONG 


; 
' Ttefine the destination file FAB and NAM cantrol blocks, 
3 


NSTOUF ARS 

Frint and delete file 
Name of file 

Name block eddress 


$F AB FORP=<SFLeDLTo9— 
FNM=<08T>s- 
NAM=DSTONAMBLK 


a> “oP ser 


USTNAMBLK $ 
$NAM RSA=DTST ORS »—- 
RSS=NAMS$C_MAXRSS 


Resultant mame string buffer 
Resultant mame string ouffer 


ap ee 


; 

+ Allocate buffer for resultant mame strings. 

3 

nRST_RS; »>BLKE NAMSC_MAXESS 5 Largest resultant mame strings 
I KKKEKKEKKKKEKKK RK KKK KKK KK RK KKK RK K KKK KAKA KKK RRR KKK KERR KAKA KR KR KKK KKKE 


»sSETTL Mainline 
sFSECT CORE NOWRTs BYTE 


Start of Frogram 


sap sar sar 


eENTRY SFOOL> “Me * Entry roint 


Oren and close the file with the FOF ferint and delete ortions srecifi 


a> > ae 


Qeen the file 
Branch on failure 


$OFEN FAR=[ST_FAR 
ELEC ROsEXIT 
$CLOSE FAB=NST_FAR 


“o> seh er “ar. 


to be ferinted and deleted 


Exit to VMS with RMS comrletion code in RO to sidnmael success or 
failure of Frogram execution, 


{TE ser ~er ses war 


XIT: $EXIT_S RO 
+ENT SFOOL 


“sr <ar 


Srecify starting address of & 


address 
Size 


ed. 


Close the file which will cause it 


Exit with RMS comeletion code in RO 


rogram 
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4.5.4.3 VAX-11 MACRO Remote File Random Access Example - Example 4-4 


accesses a relative file randomly and transfers selected records from 
one device to another. 


Example 4-4: RMS Random Access Program 


*eTITLE RANDOM ~- RANDOM ACCESS EXAMPLE 
*eIDENT /V¥O0O0O1/ 


This Frosgrem sccesses a relative file randomly by relative record 
number. It creates 3 seauential outrut file from selected records 
from the inrut file. The inrut and outrut files gre srecified by 

the logical names SRC and [STs resrectively. For exsamrle: 


$ DEFINE SRC TRNTOS {USERS CP3602.DATIEVENTLOG. DAT 
$@ DEFINE PST BOSTON? ¢TEMP.LIS 
$ RUN RANTOM 


<a> > “ab E> SP “er eR HR E> E> 


SROKA RR KKK RK RK KK KKK KK RR KKK KEK RR RK RK RK RK RK KK RK KK RK KKK KER ERE KEKE KE KKK 


*SETTL Control block and auffer storase 
>FSECT DATA NOEXE»LONG 


Tefine the source file FAR and RAK control blocks, 


“ 
? 
“ 
¥ 
a 
? 

ia 


URF=BUFFER » - 
USZ=BUFFER_SIZE 


Euffer address 
Buffer size 


SRCOUWFAR? 
$F AR FACH=<GETSs- ' File access for GET only 
FNM=<SRC> > Name of inmeut file 
SRC_RAEB? 
$RAB FAB=SRC_FABs- 5 Address of sssociated FAR 
RAC=KEYs—- > Access by relative record mumber 
KBEF=KEYOBUFFER:- ' Key buffer address 
KSZ=47- ' Key size 
5 
, 


; 
+ Define the destination file FAB and RAB control blocks. 
; 


ISTUFABR? 
$F AR FACS PUTS »- § File access for FUT only 
FOF=<SQ0>-- * Request DAF file transfer mode 
FNM=<DST»- 5 Name of outrut file 
ORG=SEQr- ' Sequential file orssnizetion 
RAT=<CRs + Imrelied carriage control 
ISTURAR: 
$RAER FAB=[ISTUFABs—- > Address of aessocisated FAB 
RAC=SEQ»- § Geauential recard access 
RBF=BUFFER + Buffer address 


5 
5 Allocate buffer to be the size of the largest record that will be read. 
5 


BUFFERS .BLKB 312 
BUFFER -SIZE=,-BUFFER 


Buffer for inrut and outrut 
Buffer size 


er a> 


Srecify record number list and sgllocate key buffer. 


sar “Oe sae 


RECORDOLIST$ 


»LONG 4st*10+0 y Record selection list terminated by 9 
KEYORUFFERS | 
»LONG 0 > Buffer to store relative record rumbe 


9 KKK KKK KK KK KKK KKK KKK KKK KK KK KA K KKK KKK KKK KKK KAR KE KK KARE KEKE KA KKK EK KKK KK 


REMOTE FILE ACCESS USING RMS 


»SBTTL Mainline 
*FSECT COLE NOWRT: BYTE 


Start of rrosgrams rut FAB and RAB addresses im resisters for efficiency, 


ep “E> ap 


*ENTRY RANDOM: “M<> 

MOVAB W°SRCFAB®RS 
MOVAR W°SRC_RAB? R7 
MOVAB W°DST_FABsRS 
MOVAR WCDSTLRABS RO 


Entry roint 

Get address of inrut FAR 
Get address of inrut KAR 
Get address of outrut FAB 
Get address of outrut RAB 


er “> wae wh WO 


Oren the source and destination files. 


a> “Pr ap 


$SOFEN FAR=R6 

BLEC ROsEXIT 

MOVB FABSB_RFM(RG) 9 - 
FARSE_RFM(CRS8) 

MOVW FARSW_MRS (RG) 2 - 
FABSW_MRSCRS) 

S$CONNECT RAB=K7 

BLBC ROVEXIT 

$CREATE FAR=RK8 

BLEC ROrEXIT 

$CONNECT RAR=K9 

BLBC ROrsEXIT 


Oren inrut file 

Branch on failure 

Cory record format attribute 
to outreut FAR 

Cory maximum record size 
attribute to outrut FAR 
Connect inrut record stream 
Branch om failure 

Create outrut file 

Branch on fseilure “ 
Conmect outrut record stream 
Branch on failure 


“a> “Or “OP wer “ah Hh OP Oe “EP SOP EP EP 


Read each record srecified in list and write it to the destination file. 


“a> s@> “oP 


MOVAB W°RECORD_LISTsRS Get record mumber vector 


3 
LOOF: MOVL CRS) +sW KEY BUFFER > Get mext record mumber 
REQL CLOSE. § All done if list terminator found 
$GET RAE=R7 + Read srecified record from inrut file 
ELEC ROrsEXIT §' Branch on failure 
NOVUW RABRSW_RSZ(R7) +- > Cory lensth of record just 
RABRSW_RSZCR9) 3 read to outrut RAK 
$PUT RAB=R9 s Write record to outrut file 
BLEC ROsEXIT ; Branch on failure 
BRE LOOF + Frocess next record 


Close the source end destination files. 


CF se> a> sw 


“LOSE? $CLOSE FAR=K8 
BLEC ROrEXIT 
$CLOSE FAR=R6 


Close outrut file 
Branch on failure 
Close inrut file 


a> wr sae 


Exit to VMS with RMS completion code in RO to signal success or 
failure of rrogram execution. 


TT] cr ee wer ~er 


XIT? $EXIT_S RO 
»ENT RANDOM 


Exit with RMS comrletion code in RO 
Specify starting address of frrogram 


“=> “we 
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4.5.4.4 VAX-11 MACRO Remote File Indexed Access Example - Example 4-5 
creates an indexed file with three keys from a sequential file on the 
local node. 


Example 4-5: RMS Indexed File Program 


*eTITLE CREATEIDX ~ CREATE INDEXED FILE 
*+IDENT /VO0O01/ 


; 

§ This Frogram creates an indexed file with three keys from 2 

5 sequential file containing 3 mame and address list. The record 
§ format of the inrut file is shown below? 

5 

5 First Neme Column O1-10 

; Middle Initial Columm Li-ti 

3 Last Neme Column 12-26 

3 Street Column 27-46 

5 City Column 47-58 

; State Column 39-460 

; Zire Code Column 61-65 

; 

§ The inrut end outrut files are srecified by the logicsel names SRC 
s and [STs resrectively. For examrle: 

y 

j $ DEFINE SRC BOSTON! !DBBLISCTESTIINFUT. DAT. 

; $ DEFINE DST TRNTOS FORA4TOCRMS.FILESIOUTFUT. DAT 

$ $ RUN CREATEIDOX 

; 

I KKKKKKEKEREREKERKKEKKRKK ERK KEK KR EK RK KK RK EKER KR EK RK EK EK KR KE KK KEKE KKK ERK 


*+SETTL Control block and buffer storage 
*-FSECT TATA NOEXE»LONG 


5 
s Ttefine the source file FAB and RAB comtrol blocks, 
; 
$ 


SRCOUF ARE 
$F AE FAC=<GET#y- $s File eccess for GET only 
FOF=<SQ027- i Reauest DAF file transfer mode 
FNM=<SRC> § Name of inreut file 
SRC_RAR?: 
$RAB | FAR=SRC_FAR?- Address of associated FAR 
RAC=SEQs- Sequential recard access 


UBF =BUFFER» ~ 
USZ=BUFFER.SIZE 


Buffer address 
Buffer size 


ep “a> “ep “E> 


Tefine the destination file FAB and RAE control blocks. 


> “@> “er 


LUSTUFARS 
$F AR FACH=SPUTS +? - § File access for FUT onls 
FNM=<0STo s- 3 Neme of outrut file 
ORG=IDXs- § Indexed file arganizaetion 
RFM=FIXs- +s Fixed length records 
RATHACR> 2 - ¢ Imrlied carriage control 
MRS=BUFFER_SIZE>s- 5 Record size 
BKS=15- + Bucket size 
XAB=0ST_KEYO s Address of start of XAB chain 
USTURAR? 
$KAE FABR=DST_UFABs - Address of associated FAR 
RAC=SEQ,- Seauential record access 


REF =BUFFER » - 
RSZ=BUFFER SIZE 


Buffer sddress 
Buffer size 


a> “Sb “EP “eS 


Define Key Definition XAERs to describe the three keys. 


“ar “> “E> 


ft 


ft 
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ST.KEYO? 
$XABKEY REF=0%- 
FOS=58%- 
SIZ=2s- 
FLG=< DUP »- 
NXT=EST_REY4 
ST_KEY1? 
SXABKEY REF=19- 
FOS=46%- 
SIZ=129- 
FLG=< DUP * » - 
NXT=LSTUKREY2 


NST.KREY23 


$XABKEY REF=2)- 
FOS=<119O0210>9- 
SIZ=L15eleiee- 
NXT=90 


Allocate buffer to be the size of the 


UFFERS .ELKB 635 
BUFFER .SIZE=.-BUFFER 


Frimary keys is State 

Key reference mumber 

Starting key rosition 

Keys size 

Durlicate keys are sllowed 
Address of next XAB in chain 

lst alternste key is City 

Key reference number 

Starting key rosition 

Key size 

Tturlicate keys are allowed 
Address of next XAB in chain 

2nd alternate key is Name 

Key reference number 

Segmented key consistins of Last Names 
First Initials and Middle Initial 
Designate end of XAB chain 


“er Sr “ae “OP See OP EP OP we ah ee OP EP ee ee OP le 


largest record that will be read, 


§ Buffer for inrut and outrut 
5 Buffer size 


FHKE KKK KKK KKK KKK KARR KKK KER KKK KK RK KR KKK KKK KKK KKK RK AK RK KK EKER KK KK KEKE 


a> “ah ser 


a> “GP sep 


"a> see wee 


E 


“ar “a> ~er 


[Tt se» ~er <> ~ae 


-SBTTL Mainline 


*PSECT CODE NOWRT? BYTE 


Stert of rrosrem 


*+ENTRY CREATEITDIX: “Me 


Oren the source and destination files. 


$OFEN FAB=SRC_FAB 
BLEC ROrEXIT 
$CONNECT RAB=SRC_RAR 
BLBC ROsEXIT 
$CREATE FAB=DST_FAR 
BLEC ROvEXIT 
$CONNECT RAR=DST_RAB 
BLBC ROvEXIT 


Transfer records until end-of-file is 


OOF: $GET RAB=SRC_RAR 
BLEC RO»sERROR 


$PUT RAB=LST_RAB 
BLBEC ROrERROR 
BRE LOOP 

RRORS CMPL RO» tRMSS$_ EOF 
BNEQ EXIT 


Entry roint 


ae 


Oren inrut file 

Branch on failure 

Conmmect inreut record stream 
Branch on failure 

Create outrut file 

Branch on failure 

Connect outrut record stream 
Branch on failure 


“> “R> MP EP EP NR eo 


reached. 


Read next record from inrut file 
Branch on failure 

Write record to outeut file 
Branch on failure 

Frocess next record 

Was it an end-of-file? 

Branch if not 


er “ar “> ‘ar “eh “OP “EP 


Close the source and destination files. 


$CLOSE FAB=DST_FAE 
BLEC RO»EXIT 
$CLOSE FAR=SRC_FAR 


Close outrut file 
Branch om failure 
Close inrut file 


a> ap ee 


Exit to VMS with RMS comreletion code in RO to signal success or 


failure of Frodram execution. 


XITs EXITS RO 
»END CREATETINNX 


Exit with RMS comrletion code in RO 
Serecify starting address of Frogram 


“ap “er 


CHAPTER 5 


TASK-TO-TASK COMMUNICATION 


Task-to-task communication is a feature common to all DECnet 
implementations that allows two programs, running under the same or 
different operating systems, to communicate with each other regardless 
of the programming languages used. For example, a FORTRAN program 
running on the VAX/VMS system at node BOSTON of our network example 
could exchange messages with a MACRO program running on the RSX-11M 
system at node DALLAS. The fact that these programs use different 
programming languages and run under different operating systems is of 
no concern to the DECnet software, which translates system-dependent 
language calls into a common set of network protocol messages. (Note 
that in the context of task-to-task communication, the terms "task" 
and "program" are used synonymously.) 


DECnet-VAX supports two forms of task-to-task communication: 
transparent and nontransparent. Transparent communication provides 
all the basic functions necessary for a program in VAX-11 MACRO or a 
higher-level language to communicate with other programs over the 
network. Nontransparent communication allows the programmer to use 
more network specific functions. 


A simple analogy differentiates these two forms of communication. 
Transparent communication is analogous to device-independent I/O under 
VAX/VMS. This form of I/O lets you move data with little concern for 
the way this is accomplished. Likewise, transparent communication 
allows you to simply move data across the network without necessarily 
knowing that you are uSing DECnet' software. Nontransparent 
communication, on the other hand, is analogous to device-dependent I/0 
wherein you are interested in specific characteristics of the device 
that you want to access. A nontransparent task, in turn, can use 
network-specific features to monitor the communication process. 


This chapter defines the forms of DECnet-VAX intertask communication 
and the general procedures necessary to implement them. Particular 
attention is paid to the DECnet interface with higher-level languages. 
The information and examples presented herein provide the necessary 
framework for the discussion of task-to-task communication in each 
higher-level language user guide. The programmer should also be 
familiar with this material before reading Chapters 6 and 7, which 
provide examples of transparent and nontransparent communication using 
system services. 


5.1 TRANSPARENT COMMUNICATION 


Transparent communication provides the basic functions necessary for a 
task to communicate with another task over the network. These 
functions include the initiation and completion of a logical link 
connection, the orderly exchange of messages between both tasks, and 
the controlled termination of the communication process. To implement 
these functions, you can program your transparent task in any of the 
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higher-level languages supported over the network or in VAX-11 MACRO, 
using RMS service calls or system service calls. 


One way to view transparent communication is to look at the 
programming required to develop such an application. Transparent 
access provides the minimum functions necessary to communicate over 
the network using standard I/O operations. When accessing the network 
transparently, you use no DECnet-specific calls to perform these 
functions; rather, you use standard RMS I/O service calls or the 
normal I/O statements provided by the applicable higher-level language 
to access a sequential record-oriented device. (The. remote task is 
modeled as a VAX/VMS mailbox to which you can perform read and write 
operations.) You can also use $QIO system service calls to perform 
transparent communication, as described in Chapter 6. 


Example 5-1 illustrates a simple example of VAX-11 FORTRAN transparent 
communication. In the source FORTRAN task that initiates the logical 
link request, you use a standard open call to specify the remote task 
to which you want to connect. In turn, the remote task issues an open 
call to complete the logical link connection. A coordinated set of 
read and write operations enable the exchange of information over the 
link. To terminate the connection, the source task executes a close 
call to break the logical link. When the remote task receives this 
close call, it issues a close call which completes’ the link 
termination process. The remaining sections of this chapter discuss 
the calls that you would use to develop such an application. 


Example 5-1: FORTRAN Task-to-Task Communication 


FROGRAM TEST3.FOR 


C 
C This rrogram Fromets the user for the eart number of an item 
C im inventory end resronds with the mumber of units in stock. 
CG The information is obtained by communicating with 3 Frosgram 
GC (TEST4) om another mode that has access to the inventory date, 
Cc 
C Before running this rrograms the logical name TASK must be 
C defined to refer to the terset rrodram. For eaxsmrle} 
C 
C: $ DEFINE TASK “TRNTO? 2 "*TASK=TEST4" °° 
Cc $ RUN TESTS 
Cc 
CHARACTER FARTNOKS 
INTEGER PARTCOUNT 

CG 
1090 FORMAT (/+’¢Enter rart number? %) 
200 FORMAT (A) : 
300 FORMAT (14) 
400 FORMAT (C’OInventorye for rart number ‘“rA9’ is% ’sI4) 
C 
C Establish a logical link with the target task. 
C 

0 OREN CUNIT=1;sNAME=’ TASK’ sACCESS=’ SEQUENTIAL ‘» 

1 FORM="’FORMATTED’ sCARRIAGECONTROL=’NONE’ » TYPE=’NEW 3 
C 
Cc Fromret the user for 2 Fart numbers send it to the target tasks - 
Cc read rerly of auantity on hands and finsglly disslay tne answer 
C for the user. Rereat the cycle until the user enters ‘EXIT’ for 
C B rart mumber-. 
C 


10 
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TYPE 100 
ACCEPT 200% FARTNO 
IF (PARTNO .EQ@. ‘EXIT’) GOTO 20 


@ WRITE (12200) FARTNO 


READ (1300) PARTCOUNT 
TYFE 400% FARTNOs FARTCOUNT 
GOTO 10 


Tisconnmect the logical link. 


@ CLOSE (UNIT#=1) 


“© 


END 


TEST4.COM 


This command rrocedure executes the rrodram TEST4 after 
heins started oy a task-to-task connection reavest issued 
by TESTS. 


UN SYSS$LOGIN:S TEST4.EXE 


Furge old log files generated by this command rrocedure, 


PURGE/KEEP=2 SYS$LOGIN: TEST4.LOG 
EXIT 


FROGRAM TEST4.FOR 


This is the target rrogram thet communicates with TESTS. 
For each Fart number received from the source tasks the 
number of units in stock is determineds and this value is 
returned, 


To comrlete the logical link with its initiator: this rrogram 
uses the losical mame SYS#$NET aes the file srecification in an 
oren statement. 


CHARACTER PARTNOXS 
INTEGER PARTCOUNT 


FORMAT (A) 
FORMAT (14) 


Comrlete the logical link connection. 


QPEN CUNIT=1*NAME=‘’SYS¢NET’ sACEESS=’SEQUENTIAL % » 
FORM=’FORMATTED’ sCARRIAGECONTROL=’NONE’sTYPE=’OLD’) 


Frocess reauests until end-of-file is reached. (This is the 
error condition returned when the source task bresks the 
logical link connection.) 


READ C1Lly1OO0,sEND=20) FARTNO 


Ferform arrrorriate frrocessing to obtain the rart count velue 
and transmit this back to the source task, 


CALL INSTOCK (CPARTNOsFARTCOUNT ) 
WRITE C1200) PARTCOUNT 
GOTO 10 
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Tlisconnmect the lasical link. 


ee a A 


0 @ cLase CUNTT=1) 
END 


Notes on Example 5-1: 


@ The source task, TEST3, requests a logical link connection to 
the target task, TEST4. 


@ When the remote node receives a connection request, the 
command procedure TEST4.COM is executed. This command 
procedure must reside under the default directory associated 
with the account being accessed. TEST4.COM contains a RUN 
statement that causes the program TEST4.EXE to be executed. 


© TEST4 completes the logical link connection via SYSSNET. 
Note that the unit numbers in the source and target programs 
need not be the same. 


@ TEST3 and TEST4 send and receive data messages. 


@ TEST3 disconnects the logical link and thereby terminates the 
communication process. 


Because DECnet-VAX translates system-dependent language calls into the 
same set of messages that permit task-to-task communication, any task 
programmed in VAX-11 MACRO or one of the higher-level languages can 
communicate with a remote task programmed in the same or a different 
language. More specifically, for communication between tasks that run 
on VAX/VMS nodes, the language in which you access the network has no 
effect on the communication process. The VAX-11 FORTRAN source’ task 
in Example 5-1 could just as easily communicate with a MACRO task on 
node TRNTO,. 


5-2 NONTRANSPARENT COMMUNICATION 


Nontransparent communication provides the same basic functions as 
transparent communication plus additional system service and I/0 
functions supported by DECnet-VAX (as described in Chapter 7.) In 
particular, a nontransparent task can create and use a VAX/VMS mailbox 
to receive information that would otherwise remain inaccessible to a 
transparent task. Thus you can use optional network protocol features 
such as optional user data on connects and disconnects, and interrupt 
messages. Also, certain nontransparent tasks that have a mailbox can 
receive and process multiple inbound connection requests. The 
discussion that follows highlights the distinctions between the two 
types of access to emphasize the additional capabilities that 
nontransparent access provides. 


Transparent communication offers the minimum functions necessary for 
initiating and completing a logical link connection, exchanging 
messages, and terminating the logical link. In fact, these functions 
are actually a subset of a larger group of functions defined for 
nontransparent communication. The entire set of functions are as 
follows: 
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e Initiating a logical link connection 
- Requesting a logical link to a remote taskl 


- Declaring a network name and processing multiple connection 
requests 


e Completing a logical link connection 
- Rejecting a logical link connection request 
- Accepting a logical link connection request! 
e Exchanging messages 
- Sending and receiving data messages! 
- Sending and receiving interrupt messages 
e Terminating a logical link 
- Synchronously disconnecting the logical link 


- Aborting the logical link! 


Nontransparent tasks can use any or all of these functions to extend 
the basic capabilities offered under transparent communication. 


5.2.1 Mailboxes and Mailbox Messages 

In general, nontransparent tasks can use a mailbox to receive 
information about particular network operations. Mailbox messages are 
of three types: 


e Messages that result from the use of certain system service 
calls (including optional user data) 


e Interrupt messages 

e Network status messages 
Nontransparent functions that indirectly cause mailbox messages to be 
placed in the receiver's mailbox include calls for initiating and 


completing logical links, and calls for terminating links. Figure 5-1 
illustrates the use of mailboxes by nontransparent tasks. 


1. Minimum subset for transparent task-to-task communication. 
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Transparent 
Task 


Connect 
Initiate 


. (Network Task) 
Task MSG$_CONNECT Task 
| 


| | 
| Mailbox 1 | Mailbox | 
| 


aS yes Connect Initiate (opt. user data) | —- — —,— 
MSGS.CONNECT, 


Connect Accept (opt. user data) 






net ee ee 






MSG$_CONFIRM 
MSG&_REJECT 


Connect Reject (opt. user data) 


A Interrupt Messages h 


MSG$_INTMSG MSG$_INTMSG 


‘ Synchronous Disconnect (opt. user data) 4 MSG$_DISCON 
MSG$_ABORT 


Disconnect Abort (opt. user data) 





DECnet-VAX Software 


Network Status Notifications: 


MSG$_EXIT 
MSG$_PATHLOST 
MSG$&_PROTOCOL 
MSG$_TIMEOUT 
MSG$_THIRDPARTY 
MSG$_NETSHUT 


ZK-840-82 


Figure 5-l: Mailbox Messages 
A nontransparent task can also receive network status notifications 
via the mailbox. These notifications apply to physical and logical 
link conditions over the network. For example, DECnet-VAX software 
can notify a nontransparent task of the following conditions: 


e Third-party disconnections (see the DECnet-VAX System 
Manager's Guide) 


@e Network software- and hardware-related problems 
e Processes exiting before I/0 completion 


e@e Connection request timeouts 
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5.3 INITIATING A LOGICAL LINK CONNECTION 


Regardless of whether you access the network transparently or 
nontransparently, you must establish a communication link to the 
remote node on which the target task runs before any message exchange 
can take place. You establish the link by issuing a source task call 
that requests a logical link connection. (To clarify, the term source 
task refers to the task that initiates a logical link connection 
request. The term target task refers to the task with which you want 
to communicate. The interaction that takes place prior to 
establishing a logical link is termed a handshaking sequence.) 


5.3.1 The Handshaking Sequence 


Upon receiving a call that requests a logical link connection, the 
local DECnet-VAX initiates a handshaking sequence with the target 
task. The following information is supplied in a connection request: 


e An I/O channel: The I/O channel serves as the path over which 
messages are sent and received by the source program. 


e The identification of the target node: Every node in a network 
has an identifier that distinguishes it from all other nodes 


in the network. Transparent communication uses a task 
specification string to indicate the name of the target node 
(see Chapter 2). Nontransparent communication requires a 


user-generated data structure called the Network Connect 
Block (NCB) which includes a task specification string (see 
Chapter 7). 


e An object type descriptor (see Chapter 2). 
e Access control information (optional; see Chapter 2). 


e Optional user data: Nontransparent tasks have the option of 
sending up to 16 bytes of data to the target program. (See 
the information on NCBs in Chapter 7.) 


Higher-level language tasks can use standard file opening statements 
to request a logical link connection to a remote task. The following 
examples in VAX-11 FORTRAN, VAX-11 BASIC, VAX-11 PL/I, VAX-11 PASCAL, 
and VAX-11 COBOL show how to specify a target task, TEST4, running on 
node TRNTO: 


FORTRAN OPEN (UNIT=7,NAME='TRNTO: :"TASK=TEST4"! , TYPE='NEW' ) 
BASIC OPEN 'TRNTO::"TASK=TEST4"' AS FILE #7 

PL/I OPEN FILE(OUTPUT) TITLE ('TRNTO::"TASK=TEST4"' ); 
PASCAL OPEN (PARTNER, 'TRNTO: :"TASK=TEST4"' ,NEW) ; 

COBOL SELECT PARTNER ASSIGN TO "TRNTO::"“TEST=TASK4""". 


OPEN OUTPUT PARTNER. 


The RMS service call equivalent to these higher-level language 
Statements is the SOPEN call. System service calls used to request 
logical link connection are described in Chapters 6 and 7. 


It is important to note that once you issue a call that uses either a 
task specification string or an NCB, you access the network and, by 


definition, DECnet-VAX software. 
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5-4 COMPLETING THE LOGICAL LINK CONNECTION 


As part of the handshaking sequence that takes place between’ the 
source and target tasks, the target task completes the logical link 
connection in two steps. First, the DECnet software at the remote 
node processes the inbound logical link connection request and then 
the target task either accepts or rejects the link. These steps are 
performed. differently, depending on whether the target task uses 
transparent or nontransparent I/O. In the following discussion, it is 
assumed that the remote node is VAX/VMS. If the remote node on which 
your target task runs is not a VAX/VMS system, you should refer to the 
DECnet documentation for that system. 


5.4.1 Completing the Connection Transparently 


If the target task is transparent, the software at the remote node 
checks the access control information supplied in the connection 
request call. DECnet-VAX software creates a process in which the 
LOGINOUT image runs. The name of this process is a concatenation of 
the name of the object connected to and the logical link number (for 
example, MAIL 65218). The LOGINOUT image verifies the access control 
information against the user name and paSsword contained in the User 
Authorization File (UAF) at the remote node. 


If the access control information is valid, LOGINOUT creates’ the 
logical name SYSSNET in the process logical name table for subsequent . 
use by the target task. The equivalence string for SYSSNET is a 
special form of file specification string that contains information 
identifying the source task which initiated the logical link 
connection. The LOGIN.COM file associated with the access control 
string is then run. Finally, the ‘command procedure file 
(taskname.COM) for starting the remote task is executed. 


Prior to your accessing the remote node, the System Manager must have 
created the appropriate account in the UAF (refer to the information 
on access control in Chapter 2.) In addition, the command procedure 
file (taskname.COM) for starting the remote task must exist in the 
directory associated with the account identified by the access control 
information. For a description of the command procedure taskname.COM, 
see Section 5.4.3. Command procedures for objects existing in the 
OBJECT data base (which is created using NCP commands). are located in 
the SYSSSYSTEM directory. 


To complete the logical link, the target task performs a file opening 
operation using the logical name SYSSNET to establish a communications 
path back to the source task. The following examples in VAX-11 
FORTRAN, VAX-11 BASIC, VAX-11 PL/I, VAX-11 PASCAL, and VAX-11 COBOL 
Show how to specify SYSSNET: 


FORTRAN OPEN (UNIT=2,NAME="SYSSNET! ,TYPE='"OLD') ) 


BASIC OPEN "SYSSNET" AS FILE #2 

PL/I OPEN FILE(INPUT) TITLE ('SYSSNET'); 
PASCAL OPEN (PARTNER, 'SYSSNET',OLD) ; 

COBOL SELECT PARTNER ASSIGN TO "SYSSNET". 


OPEN INPUT PARTNER. 


The RMS service call equivalent to these higher-level language 
statements is the SOPEN call. System service calls for accepting the 
logical link are described in Chapters 6 and 7. 
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5.4.2 Completing the Connection Nontransparently 


If the target task is nontransparent, then one of several things may 
occur. If the task has not declared itself a network task (and is 
therefore eligible to accept only one connection request at a time), 
then the DECnet software at the remote node performs the access 
checking procedure described in Section 5.4.1. After it starts, the 
target task retrieves the connection information by translating the 
logical name SYSSNET using the STRNLOG system service call (see 
Chapter 7). 


If the target task declares itself as an active network task, then 
DECnet-VAX software places all connection requests addressed to the 
task in the mailbox associated with the channel being used. The first 
message in the mailbox is the Network Connect Block (NCB) from the 
original connection request that started the task. This message 
appears in the mailbox after channel assignment and name declaration 
occur. Once the task declares a network name, subsequent inbound 
connection requests are not checked by the remote node to verify 
access control. (Note that if the task is started without being part 
of a DECnet operation, access control is never checked.) Chapter 7 
describes in more detail the nontransparent process of completing the 
logical link connection. 


After examining the incoming connection request, the target task 
either accepts or rejects the request, and optionally it can send 1 to 
16 bytes of data back to the source task at the same time that it 
responds to the logical link connection request. Furthermore, a 
library routine, LIBSASN WTH MBX, that assigns a channel and 
associates a unique mailbox, can be used when accepting the connection 
if no optional data is returned (see Section 7.2). 


5.4.3 Command Procedures Used in Task-to-Task Communication 


As described above, once the access control information is verified, 
both the LOGIN.COM command procedure for the accessed account and the 
taskname.COM command procedure in the default directory under that 


account are executed. 


On a VAX/VMS system, jobs are classified as interactive, batch, or 
network. Inclusion of the following command in the LOGIN.COM file 
avoids the execution of DCL commands applicable to the interactive 
mode that are not required for task-to-task communication. 


$ IF FSMODE() .NES. "INTERACTIVE" THEN EXIT. 


The command procedure file taskname.COM must contain at minimum a_ RUN 
command to cause the target task image to be executed. It may also 
contain terminal assignments for debugging purposes (for example, 
DBGSINPUT and DBGSOUTPUT). There are no restrictions on the type of 
commands that you can have in this file. A sample command procedure 
DEMO.COM to run the target task TASK20.EXE might contain the following 
commands: . 


$ RUN USER: [DEMO. TEMP] TASK20. EXE 
$ PURGE/KEEP=2 SYSSLOGIN: DEMO. LOG 
$ LOGOUT/BRIEF 
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A sample command procedure TEST.COM used to debug the target task 
TEXT.EXE might contain the following commands: 


$ ASSIGN TTA7: DBGSINPUT 

S$ ASSIGN TTA7: DBGSOUTPUT 

$ RUN/DEBUG SYSSLOGIN: TEST. EXE 

$ PURGE/KEEP=2 SYSSLOGIN:TEST.LOG 


The debug terminal must not currently be assigned to any process. 
Otherwise, the command procedure will exit with an error that causes 
the logical link connection to the object to be rejected. 


5.5 EXCHANGING MESSAGES 


After DECnet-VAX creates a logical link, the two tasks are ready to 
exchange messages. The exchange of messages can take place only if 
the two tasks cooperate with each other. In other words, for each 
message sent by a task, the receiving task must issue a corresponding 
call to receive the message. Also, you must decide which task will 
disconnect the link. In addition, if the tasks are nontransparent, 
they must agree on the optional data to be passed. Because either 
task can now send and receive messages, the distinction between source 
and target must be redefined. In the context of an established 
logical link, the task sending a message is the source and the task 
receiving it is the target. 


DECnet-VAX distinguishes between two types of messages: data messages 
and mailbox messages. For both transparent and nontransparent 
communication, data messages are the normal mode of information 
exchange. Nontransparent communication gives you the additional 
capability of receiving mailbox messages, such as interrupt messages, 
messages resulting from some DECnet operation (including optional user 
data), and network status notifications. 


5.5.1 Data Messages 


Whether you access the network transparently or nontransparently, 
DECnet-VAX sends data messages over a logical link in response to a 
set of send and receive calls issued by the source and target tasks. 
For higher-level language tasks, use standard read and write calls to 
send and receive data messages. In Example 5-1, the two FORTRAN tasks 
use read and write calls to exchange information. The equivalent RMS 
service calls are $GET and S$PUT. System service calls to send and 
receive data messages are described in Chapters 6 and 7. 


5.5.2 Mailbox Messages 


Nontransparent communication frequently involves using a mailbox to 
obtain network-specific information. A task may receive the following 
types of messages in its mailbox: 


e Messages that DECnet generates when a task initiates any of 
the network operations listed below (a VAX/VMS task issues 
system service calls to initiate these operations; these 
calls also permit it to place optional user data in the 
mailbox of the other task): 
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- When one task requests a logical link connection, a 
notification message (and optional user data) may be placed 
in the mailbox of the target task. 


- When a target task accepts or rejects the logical link 
connection request, a notification message (and optional 
user data) is placed in the mailbox of the source task. 


- When one task synchronously disconnects or aborts a logical 
link, a notification message (and optional user data) is 
Placed in the mailbox of the task from which it is 
disconnecting. 


e Network status notification messages that inform a task of 
some unuSual network occurrence (Such as a_e third-party 
disconnect). 


e Interrupt messages sent by the other task. 


5-6 TERMINATING THE COMMUNICATION PROCESS 


The termination of a logical link signals the end of the communication 
process between two tasks. In transparent task-to-task communication 
using higher-level language statements.or RMS service calls, either 
task can issue a file closing statement to break the link. To 
terminate the link properly, it is recommended that the receiver, and 
not the transmitter, of the final message issue the close call to 
disconnect the link. The link termination process is complete when 
the other task issues a file closing call. In transparent 
communication using system service calls, the $DASSGN system service 
call causes the link to be terminated (see Chapter 6). 


If you are using system service calls in nontransparent task-to-task 
communication, you can terminate I/O operations over a channel in one 
of three ways (as described in detail in Chapter 7): 


e Synchronous Disconnect ($QIO) - This form of disconnection 
indicates to the remote receiver that all messages sent by the 
local transmitter have been acknowledged at the Network 
Services Protocol (NSP) level. This does not guarantee that 
the user of NSP received the data. 


e Disconnect Abort ($QIO) - This form of disconnection 
indicates to the remote receiver that all messages sent have 
not necessarily been received. To ensure that all messages 
are received before the link is disconnected, the sender must 
cancel I/O on the channel before issuing the abort call. 


e Deassign Channel and Terminate Link (S$DASSGN) - This form of 
disconnection deassigns the channel and immediately 
disconnects the link. 


Note that after either a synchronous disconnect or a disconnect abort, 
you can issue a new connection request since you did not deassign the 
I/O channel but merely deaccessed the link. 


When a nontransparent task terminates the communication process, a 
notification message indicating that the link is disconnected is 
placed in mailbox of the task affected. In addition, a nontransparent 
task can send up to 16 bytes of optional user data which is also 
placed in the mailbox. 
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Note that by their nature, disconnect operations are of little value 
in guaranteeing to both partners that communication is complete. 
Therefore, it is recommended that the communicating tasks agree on a 
protocol for terminating communication. In general, the receiver and 


not the transmitter of the final message should disconnect the logical 
link. 


CHAPTER 6 


TRANSPARENT TASK-TO-TASK COMMUNICATION USING SYSTEM SERVICES 


This chapter describes the system service calls and functions that you 
can use to perform transparent task-to-task communication over the 
network. In general, transparent communication allows you to: 


e Create a logical link between tasks 
e Send and receive data messages 
e Terminate the logical link at the end of the message dialog 


This chapter defines the system service calls for these functions and 
develops an example to illustrate their use. 


The general concepts implicit in DECnet-VAX task-to-task communication 
are covered in .Chapter 5, You should also be familiar with the 
QIO-related material in the VAX/VMS System Services Reference Manual. 


The use of higher-level language statements and RMS service calis in 
transparent task-to-task communication is described in Chapter 5. 


6.1 SYSTEM SERVICE CALLS FOR TRANSPARENT COMMUNICATION 

Transparent task-to-task communication uses a set of system service 
calls available with the VAX/VMS operating system. Table 6-1 
Summarizes these calls and their specific network-related functions. 


The S$QIO calls are distinguished by function code. Section 6.7 
presents the format of these calls in more detail. 


Table 6-1: Transparent Task-to-Task Communication System 
Service Summary 


ee 


SASSIGN Request a logical link connection 
SDASSGN Terminate a logical link 


SQIO (IO$ READVBLK) Receive a message 


SQIO (I0$ WRITEVBLR) Send a message 





The system service calls summarized in Table 6-1 allow you to perform 
task-to-task communication in much the same way as you would perform 
normal I/O operations. Use the SASSIGN call to assign a logical link 
I/O channel to a "device," which in this case is a task that behaves 
like a full-duplex record-oriented device. You can perform read and 


6-1 


TRANSPARENT TASK-TO-TASK COMMUNICATION USING SYSTEM SERVICES 


write operations with this task in either a synchronous or 
asynchronous) manner. To exchange messages, use the Queue I/O (QIO) 
Requests supported by DECnet-VAX. When all communication completes, 
use the SDASSGN system service call to deassign the channel and 
thereby disconnect the logical link. 


6.2 REQUESTING A LOGICAL LINK 


To request a logical link and assign an I/O channel, use the S$ASSIGN 
system service. When you issue this call, you must include a task 
specifier for the remote node on which the cooperating task runs. The 
task specifier identifies the remote node and the target task to which 
you want to establish a logical link. (Refer to Chapter 2 for _ the 
format of the task specification string.) 


For example, for the network model described in Chapter 1, you could 
establish a logical link to target task TEST2 on node TRNTO to perform 
task-to-task communication. To create this link, code the following 
VAX-11 MACRO statements in your source program: 


TARGET: -ASCID /TRNTO: :"TASK=TEST2"/ 
NETCHAN: - BLKW 1 ; channel number returned here 
SASSIGN S DEVNAM=TARGET, CHAN=NETCHAN 


For debugging or for symmetry, you can develop and run the target task 
on the local node. Use the local node name plus two colons (::) to 
connect to the local node. Alternatively, you can use node number 0 
plus double colons (::) to connect to the local node. 


Once you establish a logical link, you refer to the assigned channel 
in any succeeding call in the MACRO program, either to send or receive 
messages, or to deassign the channel and terminate the logical link. 


Until the connection operation completes, the process is in _ Local 
Event Flag Wait (LEF) state in KERNEL mode. Therefore, pressing 
CTRL/Y will not return the process to DCL status. The maximum amount 
of time that the process will wait in this state is specified by the 
NCP command SET EXECUTOR with the INCOMING TIMER parameter. If this 
timer cannot be set to an acceptable value, tasks that accept commands 
from the terminal should use $QIO (IO$_ACCESS) instead of the 
transparent SASSIGN call to initiate logical links (see Section 
Te. Be 2 yi 


6.3 COMPLETING THE LOGICAL LINK CONNECTION 


The target task completes the logical link by specifying the logical 
name SYSSNET as the devnam argument for the SASSIGN system service. 
For example: 


LOGNAM : -ASCID /SYSSNET/ 
NETCHAN: - BLKW 1 ; channel number returned here 
SASSIGN S DEVNAM=LOGNAM , CHAN=NETCHAN 


Issue these calls in the target task to complete the logical link 
connection. The target task also specifies a channel to be used in 
subsequent system service calls. 
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In this chapter, it is assumed that the remote node is a VAX/VMS 
system. If the remote node on which the target task runs is other 
than VAX/VMS, you should refer to the related DECnet documentation. 


6.4 EXCHANGING MESSAGES 


After DECnet-VAX software establishes a logical link with the target 
task, either task can then send or receive messages. However, they 
must cooperate with each other: for each message sent with the 
SQIO (IO0$ WRITEVBLK), the other task must issue a corresponding $QIO 
(IO$_READVBLK) to receive the message. 


You must enSure that the tasks allocate enough buffer space for 
receiving the messages; if they do not, a DATAOVERUN error will 
occur. You must also ensure that the end of the dialog can be 
determined. Finally, one of the two tasks must disconnect the logical 
link. To terminate a logical link properly, the receiver, and not the 
transmitter, of the final message should break the link. 


6.5 TERMINATING THE LOGICAL LINK 


For transparent task-to-task communication, use the S$DASSGN' system 
service call to deassign the channel and break off the logical link 
with the cooperating task. This call terminates all pending calls for 
sending and receiving messages, aborts the link immediately, and frees 
the channel associated with that logical link. 


6.6 STATUS AND ERROR REPORTING 


When a system service completes execution, a status value is always 
returned. The SASSIGN, S$DASSGN, and $QIO system services place the. 
return status information in register 0 (RO). For the $QIO_ system 
service, a ‘successful status return indicates only that the request 
was successfully queued. All I/O completion status information is 
placed in the I/0 status block (IOSB). For example, a $QIO system 
service read request to a task might be successful (status return is 
SS$ NORMAL) yet fail because the link was disconnected (I/O status 
return is SS$ LINKABORT). The return status codes shown in the 
following sections may be returned both in RO and in the IOSB. 


The VAX/VMS System Services Reference Manual and the VAX/VMS I/0 


User's Guide both describe the use of asynchronous’ system 
traps (ASTs), IOSBs, and event flags. 


6.7 SYSTEM SERVICE CALL SUMMARY 


The following subsections describe the VAX/VMS system services you can 
use for transparent intertask communication. Each subsection 
describes the use of the call, its format, the arguments’ associated 
with the call, and the return status information. Appendix C lists 
the entire set of network system service error messages. 
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6.7.1 S$ASSIGN (I/O Channel Assignment) 


The SASSIGN system service assigns a channel to refer to the logical 


link. You 


can then use the channel returned in the chan argument in 


any succeeding call to send or receive a message, or to deassign the 
channel and thereby terminate the logical link. 


Format 


SASSIGN devnam ,chan ,[acmode] 


Arguments 


devnam 


chan 


acmode 


Return Status 


SS$ REMOTE 


address of a quadword descriptor of a character’ string 
that identifies the remote task. The string will 
contain either: . 


e A task specification string if the call is by the 
source task. (Refer to Chapter 2 for-the task 
specification string format.) Both the string and 
its descriptor must be in read/write storage. 


e SYSSNET if the call is by the target task. (SYSSNET 
is a logical name.) 


address of a word that will receive the assigned 
channel number. You use this channel number to send a 
message to a remote task, receive a message from a 
remote task, or to abort the logical link. 


access mode to be associated with this channel. The 
most privileged access mode used is the access mode of 
the caller. You can perform I/0 operations on_ the 
channel only from equal or more privileged access 
modes. 


The service completed successfully. (A logical 
link was established with the target task.) 


SS$_CONNECFAIL The connection to a network object timed out or 


failed. 


SS$_DEVOFFLINE The physical link is shutting down. 


SS$_FILALRACC A logical link already exists on the channel. 


SS$_INSFMEM There is not enough system dynamic memory to 


complete the request. 


SS$_INVLOGIN The access control information was found to _ be 


invalid at the remote node. 


SS$_IVDEVNAM The task specifier has an invalid format or 
content. 
SS$_LINKEXIT The network partner task was started, but exited 


before confirming the logical link (that is, 
SASSIGN to SYSSNET). 


SS$_NOLINKS No logical links are available. The maximum 


number of logical links as set for the NCP 
executor MAXIMUM LINKS parameter was exceeded. 
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SS$ _NOPRIV The issuing task does not have the _ required 
privilege to perform network operations or to 
confirm the specified logical link. 


SS$ NOSUCHNODE The specified node is unknown. 


SS$ NOSUCHOBJ The network object number is unknown at the 
~~ remote node; or for a TASK= connect, the named 
DCL command procedure file cannot be found at the 

remote node. 


SS$ NOSUCHUSER The remote node could not recognize the login 
information supplied with the connection request. 


SS$_ PROTOCOL A network protocol error occurred, most likely 
because of a network software error. 

SS$ REJECT The network object rejected the connection. 

SS$_REMRSRC The link could not be established because system 


resources at the remote node were insufficient. 


SS$_SHUT The local or remote node is no longer accepting 
connections. 


SS$ THIRDPARTY The logical link connection was terminated by a 
third party (for example, the System Manager). 


SS$_ TOOMUCHDATA The task specified too much optional or interrupt 
data. 


SS$ UNREACHABLE The remote node is currently unreachable. 


6.7.2 S$QIO (Sending a Message to a Target Task) 


The S$QIO system service with a function code of IOS WRITEVBLK sends a 
message to a target task. The $QIO call initiates an output operation 
by queuing a request to the channel associated with the logical link. 
(Alternatively, you could use the S$QIOW system service to perform the 
same operation.) 


Format 


} ga70 {teen ,chan ,func ,{iosb] ,[astadr] ,[astprm] ,pl »p2 


SQIOW 
Arguments 

efn number of the event flag to be set at request 
completion. 

chan a word containing the channel number associated with 
the logical link. Use the same channel number returned 
previously in the SASSIGN call. 

func IO$ WRITEVBLK 

iosb address of a quadword I/0 status block that is to 


receive the completion status. 
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SS$ FILNOTACC 


SS$_INSFMEM 


astadr entry point address of an AST routine that executes 
when the I/0 operation completes. If specified, the 
AST routine executes at the access mode from which the 
$QIO service was requested. 

astprm AST parameter to be passed to the AST completion 
routine. 

pl buffer address. 

p2 buffer length in bytes. 

Return Status 
SS$_NORMAL The service completed successfully. 
SS$_ABORT The I/O request has been aborted by a $DASSGN or 
SCANCEL. 
SS$_CANCEL The I/O on this channel has been cancelled. 


No logical link is associated with the channel. 


Enough memory to buffer the message could not be 


allocated. 


SS$_LINKABORT The network partner task aborted the logical 


link. 


SS$_LINKDISCON The network partner task disconnected the logical 
link. 


SS$_LINKEXIT The network partner task exited. 


SS$_PATHLOST The path to the network partner task node was 
lost. 
SS$_PROTOCOL A network protocol error occurred. This is most 


likely due to a network software error. 
SS$_THIRDPARTY The logical link connection was terminated by a 
third party (for example, the System Manager). 


6.7.3 $QIO (Receiving a Message from a Target Task) 


The $QIO system service with a function code of IO$ READVBLK receives 
a message from a target task. The S$QIO call initiates an input 
operation by queuing a request to the channel associated with the 
logical link. (Alternatively, you could use the S$QIOW system service 
to perform the same operation.) 


Format 
$QIO {res ,chan ,func ,[iosb] ,[astadr] ,[{astprm] ,pl ,p2 
SQIOW 
Arguments 
efn number of the event flag to be set at request 
completion. 
chan a word containing the channel number associated with 


the logical link. Use the same channel number returned 
previously in the SASSIGN call. 
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SS$ DATAOVERUN 


SS$_FILNOTACC 


SS$_INSFMEM 


func IO$_READVBLK 

iosb address of a quadword I/O status block that is to 
receive the completion status. 

astadr entry point address of an AST routine that executes 
when the 1/0 operation completes. If specified, the 
AST routine executes at the access mode from which the 
SQIO service was requested. 

astprm AST parameter to be passed to the AST completion 
routine, 

pl buffer address. 

p2 buffer length in bytes. 

Return Status 
SS$ NORMAL The service completed successfully. 
SS$_ ABORT The I/O request has been aborted by a S$DASSGN or 
SCANCEL. 
SS$_CANCEL The I/O on this channel has been cancelled. 


More bytes were sent than could be received in 


the supplied buffer. 
No logical link is associated with the channel. 


Enough memory to buffer the message could not be 


SS$_LINKABORT 


SS$_LINKDISCON 


SS$_LINKEXIT 


and 


the channel associated with that link. 


allocated. 


The network partner task aborted the logical 


link. 


The network partner task disconnected the logical 
link. 


The network partner task exited. 


SS$_PATHLOST The path to the network partner task node was 
lost. 
SSS$_PROTOCOL A network protocol error occurred. This iS most 
likely due to a network software error. 
SSS _THIRDPARTY The logical link connection was terminated by a 
third party (for example, the System Manager). 
6.7.4 S$DASSGN (Terminating a Logical Link) 
The SDASSGN system service terminates all pending operations to send 


receive data, disconnects the logical link immediately, and frees 


Either task can terminate the 


logical link by calling $DASSGN. 
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Format 
SDASSGN chan 
Arguments 
chan a word containing the channel number to the _ logical 
link you want disconnected. Use the same channel 


number returned previously in the SASSIGN call. 


Return Status 


SS$_ NORMAL The service completed successfully. 
SS$_IVCHAN An invalid channel number was specified. 
SS$_NOPRIV The specified channel is not assigned; or it was 


assigned from a more privileged access mode. 


6.8 PROGRAMMING EXAMPLE OF TRANSPARENT COMMUNICATION 


Example 6-1 illustrates the use of these system service calls for 
transparent task-to-task communication. TRANA is a MACRO source task 
on the local node that communicates with a target task, TRANB, on node 
TRNTO. The source task sends a connection request to the remote node 
whereupon the target task is started by the command file MTRANB.COM. 
Once the logical link connection is made, the source task sends a 
message to the target task, which in turn responds with a message and 
then waits for additional message traffic. The source task drives the 
communication process. Once the source task receives a response from 
the target task, it disconnects the link and exits, which causes the 
target task to exit also, thereby terminating the communication 
process. 


Example 6-1: Transparent Task-to-Task Communication 
Using System Services 


TRANA 


+TITLE TRANA - SOURCE TASK USING TRANSFARENT I/70 
*IDENT /V¥1.0/ 

*+SETTL WRITABLE_DATA 

*PSECT TRANASTATA SHR »NOEXE sRile WRT: BYTE 


NETCHAN:.BLKW 1 § Network chnennel 
ITOSBUF? .BLKQ 1 ¢ I/O status block 
TARGET? .ASCIO /TRNTO"MALIK KARL'S 3 "TASK=TRANE"/ * Task spec (& descrirtor) 


SENDMSG?.,ASCII /SENI THIS STRING TQ TRANE/ § Outrut buffer 
SENDMSG_SIZ=.-SENDMSG > Outrut buffer size 
RECVMSG?.ELKEB g12 y Inreut buffer 
RECVMSG_SIZ=.-RECVMSG > Ineut ouffer size 


+SETTL MAIN 
»FSECT TRANASCODE NOSHR-EXEs KD »NOWRTs BYTE 
+ENTRY STARTS “M2 sEntry Foint from exec 
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Reauest s logical link 


a> “a> “ar 


$ASSIGN_S 
DEVNAM=W" TARGET + - 
CHAN=W"°NETCHAN 
ROrsEXIT 


a> “er “ar “ee 


BLEC 


Send @ messsde to the target task. 


<a> “> ~cr 


$QIOW_S - 
EFN=#1»- 
CHAN=W°NETCHAN » - 
FUNC=S°#IO$_WRITEVBLK»— 
TOSB=W°ITOSBUF » - 
PLI=W°SENDNSG »- 


a> <a> sar “EP “Ot “EO EP “EO NEP “OP 


P2=S°#SENDIMSG_SIZ 
BLBC ROsEXIT 
MOVZWLE W°TOSKUF »RO 
BLBC ROrEXIT 


Receive @ messase from the target task 


<> “ar sar 
- 


$QIOW_S - 
EFN=#19- 
CHAN=W"°NETCHAN >» - 
FUNC=S°#1I0¢_READVELK + - 
IOSB=W"°IOSBUF » - 
FIi=W"RECVMSG»s- 
FP2=8RECVMSG_STZ 


“a> “ED See Sed Sap ee cep ee Seb ee 


BLEC ROVSEXIT 
MOVZWL W°ITOSKUF>KO 
BLBC ROrsEXIT 


Abort the logical link. 


“a> “ee ser 


SDASSGN_S - 
CHAN=W"NETCHAN 


ap ar 


Exit with status (in RO). 


fT] we wr ae 


XIT$ $EXIT_S RO 3 
; 
»END START $ 
TRANB 
*TITLE TRANE - TARGET TASK USING 
*+IDENT /V1.0/ 
*+SBTTL WRITABLE_DIATA 
*+PSECT TRANRESDATA SHR » NOEXE 
NETCHAN?. BLKW 1 
IOSBUF? .BLKQ 1 
RECVMSG?.BLKB 912 


RECVMSG_SIZ=.-RECVMSG 

LOGNAM: .ASCIL /SYS$NET/ 
SENDMSG?.ASCII /REFLY TO TRANA/ 
SENDMSG_SIZ=.-SENDIMSG 


<a> ser <a> “Gr “Or “ar ‘er 


+SBTTL MAINLINE 
*FSECT TRANRSCODE NOSHR EXE 
*+ENTRY START 9 “MA 


to the target task 


Size of 


sEntrys roint from 


and assign an I/Q channel. 
Assign 3 channel to target task 
Address of device mame descrirtor 
Adr to receive channel +* 


Branch on failure 


Issue transmit request 

Use local event flas #1 

Use assigned channel 

Write virtual pnlock 

Address of I/0 status block 
Address of outrput buffer 
Outrut buffer 
Branch om failure 

Get completion status 
Eranch on failure 


Issue receive reauest 

Use local event flags #1 

Use assigned channel 

Read virtual block 

Address of I/0 status block. 
Address of inrut buffer 
Size of inrut buffer 

Branch om failure 

Get completion status 
Branch on failure 


Tleassignm the channel 
Adr of word containing channel # 


Exit with status to be disrlayved 
om error condition 


Image transfer address 


TRANSPARENT 1/0 


sR SWRT se BYTE 


Network channel 

I/Q status block 

Ineut buffer 

Ineut ouffer size 

Lodical name & descrirtor 
Outeut buffer 

OQuteut buffer size 


sREyNOWRT es RYTE 
exec 
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“ar > > 


ASSIGNS - 
DEVNAM=W"°LOGNAM > - 
CHAN=W"NETCHAN 

BLEC ROrEXIT 

OOF; 


Receive message from source task, 


~er <a> ser 


$#QIOW_S - 
EFN=#15- 
CHAN=W"NETCHAN? - 


FUNC=S°#I0$_READVELK »— 


TOSB=W°TOSBUF » - 
P1L=W°RECVMSG» - 
P2=#RECVMSG_SIZ 


BLEC ROrEXIT 

MOVZWL W°ITOSKUFsRO 
CMFW S“#SS$_ABRORTsRO 
REQL NONE 

RLBC ROrEXIT 


Send message to source task. 


ser “a> sar 


$QIOW_S - 
EFN=#1I-~- 
CHAN=W°NETCHANs» — 


FUNC=S°#I0$_WRITEVELK» - 


IOSK=W" 1LOSBUF » ~ 
P1=W°SENDIMSG » - 
P2=S°#SENDIMSG. SIZ 


BLEC RO,EXIT 
MOVZWL W°IOSRKUF*RO 
RLEC ROLEXIT 

RRB LOOF 


3 
§ Logical link wes aborted. 
> 


TONE $ $IASSGN_S - 
CHAN=W"NETCHAN 
; 
> Exit with status Cim RO). 
; 
EXIT? $EXIT_S RO 
~-ENL START 


Comrlete the lodical link connection 


(that TRANA reauested?),. 


“ar ee wr Oe “ee ee ae ee we Pe nap OP ‘er “er wae ‘er 


<a> Suh ah em See ser ee ee ee ser wer 


> “e> 


“> sop 


. 
y 


Assign chanmmel to SYS#NET 
Descrirtor of SYS#NET 
Store channel # 

Eranch on failure 


Issue receive reruest 

Use local event fleas #1 
Use assigned channel 

Read virtual block 
Address of I/0 status block 
Address of inrut buffer 
Size of inrut buffer 
Branch on fsilure 

Get comrletiaon status 

Was losdicel link saborted? 
Branch if yes 

Branch on failure 


Issue transmit reauest 
Use locel event flag #1 
Use assigned channel 
Write virtual block 
Address of I/0 status block 
Address of outrut ouffer 
Size of outrut buffer 
Branch on failure 

Get completion status 
Branch on failure 
Reissue the read 


Teassidn the channel 
Address of channel # 


Exit with status to he disrlased 
on error condition 


Image transfer address 
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NONTRANSPARENT TASK-TO-TASK COMMUNICATION USING SYSTEM SERVICES 


This chapter describes the system service calls and functions that you 
use to perform nontransparent task-to-task communication. In general, 
the underlying principles of nontransparent task-to-task communication 
are Similar to those of transparent communication. However, several 
extensions to the system services described in Chapter 6 allow you to 
use network-specific features for network operations. These 
extensions allow you to do the following: 


e Create and use mailboxes for receiving messages, including 
network status notifications 


e Declare a task as a network task, thus enabling it to process 
multiple inbound logical link connection requests 


e Send connection requests, optionally with user data 


e Accept or reject a connection request, optionally with user 
data 


e Communicate between a transparent and a nontransparent task 
e Send or receive an interrupt message 


e Synchronously disconnect or disconnect abort a logical link, 
optionally with user data 


This chapter defines the system service calls for these functions and 
presents an example to illustrate their use. 


The general concepts implicit in DECnet-VAX task-to-task communication 
are covered in Chapter 5. You should also be familiar with the 
material contained in the VAX/VMS System Services Reference Manual and 


7.1 SYSTEM SERVICE CALLS FOR NONTRANSPARENT COMMUNICATION 


Nontransparent task-to-task communication over the network uses a set 
of system service calls available under the VAX/VMS operating system. 
Table 7-1 summarizes these calls and their network-related functions. 
The $QIO calls are distinguished by function code. (Section 7.8 
presents the format of these calls in more detail.) 
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Table 7-1: Summary of System Service Calls for Nontransparent 
Task-to-Task Communication 


ee ee 


SASSIGN Assign an I/O channel 
SCANCEL Cancel I/O on a channel 
SCREMBX Create a mailbox 


SDASSGN Abort the logical link 
connection (deassigning an 
I/O channel) 


SGETDVI Get information on device 
or volume 


$QIO (I0$ ACCESS) Request a logical link 
connection 


SQIO (I0$ ACCESS) Accept a logical link 
connection request 


$QIO (IO0$_ACCESS!IO$M_ ABORT) Reject a logical link 
connection request 


SQIO (I0$ ACPCONTROL) Assign a network name to a 
task eligible to accept 
multiple inbound connection 
requests 


SQIO (I0$ DEACCESS!IOSM_ ABORT) Abort the logical link 
connection 


SQIO (IO$ DEACCESS!I0$M SYNCH) Synchronously disconnect a 
~ logical link 


SQIO (I10$ READVBLK) Receive a message 
$QIO (10$ WRITEVBLK) Send a message 
SQIO (IO$ WRITEVBLK!IOS$M_ INTERRUPT) Send an interrupt message 


STRNLOG Translate logical names 





7.2 ASSIGNING A CHANNEL TO NET: AND CREATING A MAILBOX 


To prepare for nontransparent task-to-task communication, you need. to 
assign a channel just as you would for transparent communication. In 
addition, to take advantage of optional network protocol features, you 
can create a mailbox. 


For task-to-task communication, you must assign a channel to a 
pseudo-device called NET:. Use the SASSIGN system Service call for 
this purpose. This calI normally contains a reference to a mailbox, 
thereby associating it with the channel assigned to NET:. If you use 
a mailbox, you must create the mailbox before assigning a channel to 
_NET:, It is important to note that this use of the S$ASSIGN system 
service differs from its use for transparent communication. Assigning 
a channel to NET: does not transmit a logical link connection 
request to the remote node. Instead, the channel to NET: provides a 
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communication path to DECnet’ software. A separate SQIO call 
(IO$_ ACCESS function using the same channel) must be used to request a 
logical link to the remote task. 


To take advantage of optional network protocol features, you can 
create a mailbox to receive messages on behalf of logical link 
operations. For example, the mailbox receives a message indicating 
whether the cooperating task accepted or rejected a connection request 
issued by the source task. Use the SCREMBX system service to create a 
mailbox for these purposes. In the event that your application does 
not use mailbox messages, you need not create a mailbox. 


For convenience, the run-time library routine LIBSASN WTH MBX can be 
used to create a temporary mailbox, assign a channel to it, and assign 
a channel to NET:. This routine creates a unique mailbox such that 
multiple copies of the task using it will in effect use different 
mailboxes. If you were to create a mailbox with a logical name, all 
tasks would use the same mailbox and thereby interfere with each 
other's mailbox messages. The program example in Section 7.9 
illustrates a use of this’ routine. Refer to the VAX-11 Run-Time. 
Library Reference Manual for a complete description of this routine. 


722.1 Mailbox Message Format 
The mailbox receives information specific to nontransparent 


communication with a remote task. Figure 7-1 illustrates the general 
format of the mailbox message. 


16,15 87 0 


UNIT MSGTYPE 


COUNT 
COUNT 


ZK-841-82 
















Figure 7-1: Mailbox Message Format 


Notes to Figure 7-1: 
MSGTYPE Contains a code that identifies the message type. 


UNIT Contains the binary unit number of the device for which 
the message applies. 


COUNT Contain a counted ASCII string that gives the name of 
NAME the device for which the message applies. The S$ASSIGN 

system service creates devices having names of "NET". 
COUNT Contain a counted ASCII string of information which 
INFO depends on the message type. 


Appendix D summarizes the mailbox messages that pertain to 
nontransparent task-to-task communication. 
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7-3 REQUESTING A LOGICAL LINK CONNECTION 


Once you assign the I/O channel, you can then request a logical link 
connection. To request a logical link connection to the target task, 
use the $QIO system service with a function code of I0$ ACCESS. You 
must identify the target task in the $QIO call. Use a Network Connect 
Block (NCB) to specify the target task identification string. In 
addition, you can optionally send 1 to 16 bytes of data in the NCB. 
The NCB must be in read/write storage. The format of the NCB is 
discussed in Section 7.3.1. 


Once the source task issues the connection request, it can then issue 
a $QI0O call with a function code of IO$ READVBLK to read its mailbox. 
Checking the contents of the mailbox is one way to determine whether 
the target task accepted or rejected the connection request. The 
mailbox will contain either MSG$ CONFIRM or MSGS REJECT, possibly with 
optional data in the mailbox buffer. F 


If specified, the IOSB argument of the $QIO (I0$ ACCESS) call will 
also contain the result of the connection request operation. Section 
7.8.2 provides a complete list of I/O status messages for this call. 


Note that you must read the mailbox to inspect any optional data _ sent 
from the target task upon accepting or rejecting the connection 
request. 


7.3.1 Network Connect Block 


The Network Connect Block (NCB) is a user-generated data structure 
that contains the information necessary to request a logical link 
connection, or to accept or reject a logical link connection request. 


Figure 7-2 is an example of an NCB you could use when issuing a 
connection request call. 


The significance of the information contained in the NCB block varies, 
depending on the type of call in which it is used. If the call is an 
outbound connection request with no optional data, items 2, 3, 4, and 
5 of the block are not required. If the call is a connect accept 
operation and no optional data is sent, then items 4 and 5 are not 
required. Item 5 is meaningful only to the receiver of a connection 
request. 


The example in Figure 7-2 illustrates an NCB that you could use when 
issuing a connection request call. 
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1. With optional data (outbound connect): 


NCB: -ASCII Pee dere 
-WORD 060 

OPTDATA: 
-ASCIC /USERINFO/  @ 
-BLKB 17-<.-OPTDATA> 


-ASCII /"/ 
© 


2. Without optional data (outbound connect): 


NCB: -ASCII ?TRNTO: :"TASK=TEST2"? 





Item Function 


@ A valid task specification string. (Refer to Chapter 2 for 
the task specification format.) For an inbound call with an 
NCB, the task name portion of the task specification string is 
a process ID if the remote node is a VAX/VMS system; if not, 
then the task name portion is a system-specific string that 
identifies an executable unit (for example, job or task). The 
task specification string must be a quoted string. Note that 
the final quotation mark of the task specification string 
follows the last item within the NCB. 


@ The slash character (/). 


© One word. This word must be 0 for a connection request 
operation. For a connect accept or reject operation, this 
word contains an internal DECnet link identifier. 


@ Up to 16 bytes of optional data sent as a counted string. 
This string is stored in a fixed length field that is 17 bytes 
long. DECnet-VAX software ignores unused bytes. 


@ A destination descriptor. (This indicates how the connection 
was issued and is meaningful only to the task or object to 
which the connection is made. This information is useful 
where one program serves many functions and needs to know how 
it was invoked.) The maximum length for the destination 
descriptor is 19 bytes. The format is as follows: 


a. If byte 0 contains 0, then byte 1 is the binary value of 
the object number. 


b. If byte 0 contains 1, then byte 1 is the binary object 
number, and bytes 2 through 18 contain a counted task 
name. 


c. If byte 0 contains 2, then byte 1 is the binary object 
number, bytes 2 through 5 contain a UIC, the first two 
bytes of which contain a binary group code and the’ second 
two bytes contain a binary user code, and bytes 6 through 
18 contain a counted task name. 


Figure 7-2: Network Control Block Format 


7.4 COMPLETING THE LOGICAL LINK 


A nontransparent target task completes the logical link connection 
in one of several ways, depending upon whether the task can process 
multiple inbound connection requests or just a single request. 
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Furthermore, a nontransparent target task has the option of either 
accepting or explicitly rejecting a logical link request. 


In the discussion that follows, it is assumed that the remote node 
is VAX/VMS. If the remote node on which your target task runs is 
other than VAX/VMS, you should refer to the related DECnet 
documentation. 


7.4.1 Receiving a Connection Request 


When a remote node receives a call requesting a logical link, the 
DECnet-VAX software constructs an NCB from the information contained 
in the call. At this point, one of two things occurs. If a process 
already running on the remote node has declared a network name or 
object number the same as the one identified in the NCB, then the 
software puts the NCB into its mailbox. If not, DECnet-VAX software 
creates a process that runs the LOGINOUT image. The LOGINOUT image 
verifies the access control information and, if it checks out, 
LOGINOUT equates SYSSNET to the NCB, invokes LOGIN.COM (if it 
exists), and starts the taskname.COM command file. The name of this 
command file is determined as follows: 


e If the connection request identifies a numbered (nonzero) 
object, then the appropriate record is located in the 
Configuration Data Base and the name of the file is found in 
this record. (The file is assumed to be found in 
SYSSSYSTEM.) 


e If the connection request identifies a named object with 
type 0 (TASK), then the file name is assumed to be the name 
of the task connected to (with a file type of .COM) and is 
assumed to be found in the default directory associated with 
the access control information. 


Once executing, the target task can then determine whether to accept 
or explicitly reject the connection request. You can program the 
target task to base this assessment on the information contained in 
the NCB. 


7.4.1.1 Receiving Single Connection Requests —- A. nontransparent 
target task can accept only one connection request at a time, unless 
it declares itself as a network task. The target task may retrieve 
the connection information by translating the logical name SYSSNET 
using the S$TRNLOG system service call. Once the task retrieves the 
logical name, it may then decide whether to accept or explicitly 
reject the connection request. 


Note that you need not translate SYSSNET if the following 
information is not required: 


e The optional data in the Network Connect Block 
e The identity of the connector 


e The descriptor by which the connection was made 
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7.4.1.2 Receiving Multiple Connection Requests (Network Tasks) - A 
target task can accept multiple inbound connection requests only if 
it declares itself a known network task. To make this declaration, 
you must first use the SASSIGN call to assign an I/O channel to 
NET:. Then, use the $QIO system service with a function code of 
TO$ ACPCONTROL to assign a network name or object number to the 
task, making it eligible to process multiple inbound connection 
requests. This system service requires SYSNAM privilege. You must 
associate a mailbox with the channel if a name or number is to be 
declared. 


Programs that have declared names or object numbers should be 
programmed to terminate when their mailboxes receive a MSGS NETSHUT 
message. Such programs must be restarted when the network comes 
back up. 


Once you declare the target task as an active network task, DECnet 
places all connection requests addressed to the task in the mailbox 
associated with the channel over which the ACP control function was 
issued. The target task retrieves connection requests from the 
mailbox by issuing the SQIO system service call with a function code 
of I0$ READVBLK. Note that the first message in the mailbox is the 
NCB from the original connection request that put the task into a 
state of execution. Once the task declares a network name or object 
number, subsequent inbound connection requests are not checked _ for 
their access control information. (However, if the network task is 
started separately from a DECnet operation, access control is never 
checked.) 


Note that you can start programs that declare names or object 
numbers apart from the first inbound connection (that is, by a RUN 
command) . 


7.4.2 Accepting or Rejecting a Connection Request 


As mentioned previously, the target task can either accept or 
explicitly reject a connection request. To accept a connection 
request, thus completing the logical link connection, use the $QIO 
system service with a function code of I0$ ACCESS. To reject the 
connection request, use the $QIO system service with the function code 
I0$ ACCESS!IOSM ABORT. When it either accepts or rejects’ the 
connection request, the target task can also send 1 to 16 bytes of 
optional data within a modified NCB back to the source task. 


7.5 EXCHANGING MESSAGES 


Exchange of data messages between the two cooperating tasks is 
performed in the same way for both nontransparent and transparent 
communication. (Refer to Section 6.4 for information on using the 
system service calls $QIO (I10$ WRITEVBLK) and $QIO (IO$ READVBLK) to 
send and receive messages.) In addition, the following information on 
interrupt messages is particular to nontransparent communication. 


7.5.1 Interrupt Messages 


Either task can send a 1- to 16-byte interrupt message. You can use 
this method to send a message to a target task outside the normal flow 
of data messages. DECnet-VAX places the received interrupt message in 
the target task's mailbox. Use the S$QIO system service with a 
function code of I0$ WRITEVBLK!IOSM INTERRUPT to send the interrupt 
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message. In order for the target task to be notified that an 
interrupt message has been placed in its mailbox, the task should 
issue a $QIO system service call with a function code of I0O$ READVBLK 
to the mailbox. Specifying an AST routine in the $QIO system service 
call will cause the routine to be executed on receiving the interrupt 
message. (AST routines are described in the VAX/VMS System Services 
Reference Manual.) 


7-6 DISCONNECTING OR ABORTING THE LOGICAL LINK 


A nontransparent task can terminate communication with a remote’ task 
in one of two ways: either by disconnecting the link (synchronous 
disconnect or disconnect abort) or by deassigning the channel. In the 
first instance, you can issue a new connection request on the same 
channel since you do not deassign it. Regardless of the method you 
choose, you can send an optional message of 1 to 16 bytes of data with 
the $QIO call. 


7.6.1 Synchronously Disconnecting a Logical Link 


To synchronously disconnect a logical link, issue the S$QIO_ system 
service with a function code of IO$ DEACCESS!IOSM SYNCH. The channel 
is then free for subsequent communication with either the same or a 
different remote task. 


A synchronous disconnection is useful for master/slave communication 
in which one task always sends data and its partner task always 
receives that data. If the receiver sees a synchronous disconnection 
notification, it knows that it received all the data that was sent. 
(The sender on the other hand is not guaranteed that its partner 
received the data.) Because this is the only guarantee provided by 
this operation, using this operation is discouraged in favor of a 
user-defined protocol to ensure completion of communication. In 
cece the receiver of the final message should break the logical 
ink. 


7.6.2 Aborting the Logical Link ($QIO Function) 


To abort the logical link, issue the $QIO system service with a 
function code of IOS DEACCESS!IOSM ABORT. This form of disconnection 
indicates to the receiver that not all messages sent have necessarily 
been received. To ensure that all transmitted messages have been 
received, the task itself must terminate I/O operations on the _ link 
before instituting the DEACCESS function because this function never 
completes before all pending I/O operations complete. To do so, first 
issue the $CANCEL system service to terminate I/O operations over the 
link; then, issue the $QIO system service to terminate the link. 


Note that after either a synchronous disconnect or a disconnect abort, 
you can issue a new connection request if you did not deassign the I/0 
channel. 


If you issue the $CANCEL system service to a channel over which a 
network name or object has been declared, the declaration will be 
removed from the network data base. 


NONTRANSPARENT TASK-TO-TASK COMMUNICATION USING SYSTEM SERVICES 


7.6.3 Terminating the Logical Link (SDASSGN Function) 


You can issue the $DASSGN system service call to deassign the channel 
and terminate the logical link immediately. You issue the $DASSGN 
call only after all communication between the tasks is complete. The 
call releases the 1/0 channel, disassociates the mailbox from the 
channel, and terminates the logical link immediately. This operation 
is equivalent to using SCANCEL followed by SQIO 
IO$_ DEACCESS!IO$M ABORT. 


7.7 STATUS AND ERROR REPORTING 


The same status and error’ reporting considerations apply to 
nontransparent as to transparent task-to-task communication. Refer to 
Section 6.6 for information on status and error reporting. 


7.8 SYSTEM SERVICES CALL SUMMARY 


The following subsections describe the VAX/VMS system services you can 
use for nontransparent intertask communication over the network. Each 
subsection describes the use of the call, its format, the arguments 
associated with the call, and the return status information. Appendix 
C lists the entire set of network system service error messages. 


The following system services are not described in detail below, 
because their usage is the same whether or not they are used ina 
networking context. For a description of these system services, see 
the VAX/VMS System Services Reference Manual. 


er Ne 


SCANCEL Cancel I/O on Channel 
SCREMBX Create Mailbox and Assign Channel 
SGETDVI Get Device/Volume Information 


Note that SGETDVI performs the same function as the Get I/O Channel 
Information (SGETCHN) system service. However, DIGITAL recommends 
that you use the $GETDVI system service. 


7.8.1 SASSIGN (I/O Channel Assignment) 
The SASSIGN system service assigns a channel to refer to a logical 
link. You use this channel in all $QIO calls that communicate with a 


remote task. In addition, you can use the SASSIGN system service call 
to associate a mailbox with the channel. 


Format 


SASSIGN devnam ,chan ,[acmode] , [mbxnam] 


Arguments 

devnam address of a quadword descriptor of a character string 
containing the string NET: or a logical name for 
_NET:. 

chan address of a word that will receive the assigned 
channel number. 

acmode access mode to be associated with this channel. The 
most privileged access mode used is the access mode of 
the caller. You can perform I/0 operations on the 
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mbxnam 


Return Status 


channel only from equal or more privileged access 
modes. 


address of a character string descriptor for the 
physical name of the mailbox to be associated with the 
channel. This mailbox remains associated with the 
channel until the channel is deassigned ($DASSGN). 


SS$_NORMAL The service completed successfully. 


SS$_INSFMEM There is not enough system dynamic memory to 


complete the request. 


SS$_NOPRIV The issuing task does not have the required 


privileges to create a logical link to the 
designated target. 


SS$_NOSUCHDEV The network device driver is not loaded (for 


example, the DECnet-VAX software is not 
running currently on the local node). 


7.8.2 $QIO (Requesting a Logical Link Connection) 


The $QIO system service with a function code of IO$ ACCESS requests a 
logical link connection to a target task. You can send 1 to 16 bytes 
of optional data to the target task at the same time that you issue 
the S$QIO system service. 


Format 


SQIO [efn] 


Arguments 


efn 


chan 


func 


iosb 


astadr 


astprm 


pl 


p2 


,chan ,func ,[iosb] ,[astadr] ,[fastprm] ,[{pl] ,p2 


number of the event flag to be set at request 
completion. 


address of a word containing the channel number 
associated with the logical link. Use the same channel 
number returned previously in the SASSIGN call. 


I0$ ACCESS 


address of a quadword I/0 status block that is to 
receive the completion status. 


entry point address of an AST routine that executes 
when the 1/0 operation completes. If specified, the 
AST routine executes at the access mode from which the 
S$QIO service was requested. 


AST parameter to be passed to the AST completion 
routine. 


not used (omit the argument). 
address of a quadword descriptor of the NCB (see 


Section 7.3.1). Both the descriptor and the NCB must . 
be in read/write storage. 


Return Status 


SS$ NORMAL 


SS$ CONNECFAIL 
SS$_DEVOFFLINE 
SS$_FILALRACC 
SS$_INSFMEM 
SS$_INVLOGIN 
SS$_IVDEVNAM 


SS$ LINKEXIT 


SS$_NOLINKS 


SS$ NOPRIV 


SS$_NOSUCHNODE 


SS$ NOSUCHOBJ 


SS$ NOSUCHUSER 
SS$ PROTOCOL 


SS$ REJECT 
SS$_REMRSRC 

SS$ SHUT 
SS$_THIRDPARTY 
SS$_TOOMUCHDATA 


SS$_UNREACHABLE 
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The service completed successfully. 


The connection to a network object timed out 
or failed. 


The physical link is shutting down. 


A logical link is already accessed on the 
channel (that is, a previous connect on the 
channel). 


There is not enough system dynamic memory to 
complete the request. 


The access control information was found to 
be invalid at the remote node. 


The NCB has an invalid format or content. 


The network partner task was started, but 
exited before confirming the logical link 
(that is, SASSIGN to SYSSNET). 


No logical links are available. The maximum 
number of logical links as set for _ the 
executor MAXIMUM LINKS parameter was 
exceeded. 


The issuing task does not have the required 
privileges to create a logical link to the 
designated target. 


The specified node is unknown. 

The network object number is unknown at the 
remote node; or for a TASK= connect, the 
named DCL command procedure file cannot be 
found at the remote node. 


The remote node could not recognize the login 


information supplied with the connection 
request. 
A network protocol error occurred. This 


error is most likely due to a network 
software error. 


The network object rejected the connection. 
The link could not be established because 
system resources at the remote node were 


insufficient. 


The local or remote node is no 
accepting connections. 


longer 
The logical link was terminated by a third 
party (for example, the System Manager). 


The task specified too much optional or 
interrupt data. 


The remote node is currently unreachable. 
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7.8.3 $QIO (Accepting a Logical Link Connection Request) 


The $QIO system service with a function code of IO$ ACCESS accepts a 
logical link connection request from a source task. You can send 1 to 
16 bytes of optional data to the source task at the same time that you 
issue the S$QIO system service. 


Format 


S$QIO [efn] ,chan ,func ,[iosb] ,{astadr] ,[astprm] ,[pl] ,p2 


Arguments 


efn 


chan 


func 


iosb 


astadr 


astprm 


pl 
p2 


Return Status 


number of the event flag to be set at request 
completion. 


address of a word containing the channel number 
associated with the logical link. Use the same channel 
number returned previously in the SASSIGN call. 


I0$ ACCESS 


address of a quadword I/O status block that is to 
receive the completion status. 


entry point address of an AST routine that executes 
when the I/0 operation completes. If specified, the 
AST routine executes at the access mode from which the 
SQIO service was requested. 


AST parameter to be passed to the AST completion 
routine. 


not used (omit the argument). 
address of a quadword descriptor of the NCB (see 


Section 7.3.1). Both the descriptor and the NCB must 
be in read/write storage. 


SS$_NORMAL The service completed successfully. 

SS$_DEVALLOC The process cannot access the logical link 
specified in the NCB’ because that link is 
intended for another process. 

SS$_EXQUOTA The process does not have sufficient quota to 
complete the request. 

SS$_INSFMEM There is not enough system dynamic memory to 
complete the request. 

SS$_IVDEVNAM The NCB has an invalid format or content. 

SS$_LINKABORT The network partner task aborted the logical 
link. 

SS$_LINKDISCON The network partner task disconnected the 
logical link. 

SS$_LINKEXIT The network partner task exited. 

SS$_NOSUCHNODE The specified node is unknown. 
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SS$_PATHLOST The path to the network partner task node was 
lost. 

SS$_ PROTOCOL A network protocol error occurred. This 
error is most likely due to a network 
software error. 

SS$_THIRDPARTY The logical link connection was terminated by 
a third party (for example, the System 
Manager). 

SS$_ TIMEOUT The connection request did not complete 
within the required time. 

SSS UNREACHABLE The remote node is currently unreachable. 


7.8.4 $QIO (Re 
The S$QIO system 
rejects a logic 
of optional dat 
the $QIO system 
Format 

$QIO [efn] 


Arguments 


efn 


chan 


func 


iosb 


astadr 


astprm 


pl 
p2 


Return Status 


SS$ NORMAL 


SS$_DEVALL 


jecting a Logical Link Connection Request) 


service with a function code of I0$ ACCESS!IO$M ABORT 
al link connection request. You can send 1 to 16 bytes 
a to the target task at the same time that you issue 


service. 


,chan ,func ,{iosb] ,[{astadr] ,[astprm] ,[{pl] ,p2 


number of the event flag ,to be set at request 
completion. 


address of a word containing the channel number 
associated with the logical link. Use the same channel 
number returned previously in the SASSIGN call. 


IO$_ACCESS!IO$M ABORT 


address of a quadword I/O status block that is to 
receive the completion status. 


entry point address of an AST routine that executes 
when the I/0 operation completes. If specified, the 
AST routine executes at the access mode from which’ the 
SQIO service was requested. 


AST parameter to be passed to the AST completion 
routine. 


not used (omit the argument). 
address of a quadword descriptor of the NCB (See 


Section 7.3.1). Both the descriptor and the NCB must 
be in read/write storage. 


The service completed successfully. 
oc The process cannot access the logical link 


specified in the NCB’ because that link is 
intended for another process. 
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SS$_EXQUOTA The process does not have sufficient quota to 
complete the request. 

SS$_IVDEVNAM The NCB has an invalid format or content. 

SS$_LINKABORT The network partner task aborted the logical 
link. 

SS$ LINKDISCON The network partner task disconnected the 
logical link. 

SS$_LINKEXIT The network partner task exited. 

SS$_NOSUCHNODE The specified node is unknown. 

SS$_TIMEOUT The connection request did not complete 
within the required time. 

SS$_PATHLOST The path to the network partner task node was 
lost. 

SS$_PROTOCOL A network protocol error occurred. This 
error is most likely due to a network 


software error. 


SS$_THIRDPARTY The logical link connection was terminated by 
a third party (for example, the System 
Manager). 


SS$_UNREACHABLE The remote node is currently unreachable. 


7.8.5 S$QIO (Sending a Message to a Target Task) 
The $QIO system service with a function code of IO$ WRITEVBLK sends a 


message to a target task. Refer to Section 6.7.2 for the format of 
this call, its arguments, and possible return status codes. 


7.8.6 $QIO (Receiving a Message from a Target Task) 
The $QIO system service with a function code of IO$ READVBLK receives 


a message from a target task. Refer to Section 6.7.3 for the format 
of this call, its arguments, and possible return status codes. 


7.8.7 $QIO (Sending an Interrupt Message to a Target Task) 
The $QIO system service with a function code of 
IO$ WRITEVBLK!IOS$M_INTERRUPT sends a 1- to 16-byte interrupt message 
to a target task. If the remote node is a VAX/VMS system, the message 
is placed in the mailbox associated with the target task. 
Format 

SQIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,pl ,p2 


Arguments 


efn number of the event flag to be set at event completion. 
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chan 
func 
iosb 


astadr 


astprm 


pl 


p2 


Return Status 


address of a word containing the channel number 
associated with the logical link. Use the same channel 
number returned previously in the SASSIGN call. 


IO$_WRITEVBLK!IOSM_ INTERRUPT 


address of a quadword I/0 status block that will 
receive the completion status. 


entry point address of the AST routine that executes 
when the I/0 operation completes. If specified, the 


AST routine executes at the access mode from which the 
SQIO service was requested. 


the AST parameter to be passed to the AST completion 
routine. 


buffer address. 


buffer length (1 to 16 bytes). 


SS$_NORMAL The service completed successfully. 

SSS$_ABORT The I/O request has been aborted by a S$SDASSGN 
or SCANCEL. 

SS$_FILNOTACC No logical link is associated with the 
channel. 

SS$_INSFMEM Enough memory to buffer the message could not 
be allocated. 

SS$ LINKABORT The network partner task aborted the logical 
link. 

SS$_LINKDISCON The network partner task disconnected the 
logical link. 

SS$ _LINKEXIT The network partner task exited. 

SS$ _NOSOLICIT DECnet could not accept an interrupt message 
at this time. 

SS$_TOOMUCHDATA The task specified too much interrupt data. 

SS$_PATHLOST The path to the network partner task node was 
lost. 

SSS$_PROTOCOL A network protocol error occurred. This 
error is most likely due to a network 
software error. 

SS$_THIRDPARTY The logical link connection was terminated by 


a third .party (for example, the System 
Manager). 


7.8.8 $QIO (Synchronously Disconnecting a Logical Link) 


The $QIO system service with a function code of I0$ DEACCESS!IO$ SYNCH 
Synchronously disconnects the logical link. All pending messages are 
transmitted to the remote node before the link is disconnected. 
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You can send 1 to 16 bytes of optional data to the task from which you 
are disconnecting at the same time you issue this $QIO system service. 
Format 


SQIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,(pl] ,(p2] 


Arguments 

efn number of the event flag to be set at event completion. 

chan address of a word containing the channel number 
associated with the logical link. Use the same channel 
number returned previously in the SASSIGN call. 

func IO$_DEACCESS!IO$M_SYNCH 

iosb address of a quadword I/0 status block that will 
receive the completion status. 

astadr entry point address of the AST routine that executes 
when the I/0 operation completes. If specified, the 
AST routine executes at the access mode from which the 
SQIO service was requested. 

astprm the AST parameter to be passed to the AST completion 
routine. 

pl not used (omit the argument). 

p2 address of a descriptor of a counted ASCII string of 


optional user data. Both the string and its descriptor 
must be in read/write storage. 


Return Status 


SS$_ NORMAL The service completed successfully. 
SS$_FILNOTACC No logical link is associated with the 
channel. 


7.8.9 $QIO0 (Aborting a Logical Link) 


The SQIO system service with a function code of IO$ DEACCESS!IO$ ABORT 
terminates the logical link. Note, however, that the DEACCESS 
function completes only after all pending I/0 operations complete, 
even though you specify IO$ ABORT. First, issue the S$CANCEL system 
service call to cancel I/O operations on the logical link and _ then 
issue this call to terminate the logical link. 


You can send 1 to 16 bytes of optional data to the task from which you 
are disconnecting at the same time that you issue this $QIO system 
service call. 
Format 

S$QIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[pl] ,[p2] 


Arguments 


efn number of the event flag to be set at event completion. 
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chan address of a word containing the channel number 
associated with the logical link. Use the same channel 
number returned previously in the SASSIGN call. 


func I0$_DEACCESS!IO$M ABORT 


iosb address of a quadword I/O status block that will 
receive the completion status. 


astadr entry point address of the AST routine that executes 
when the I/0 operation completes. If specified, the 
AST routine executes at the access mode from which the 
SQIO service was requested. 


astprm the AST parameter to be passed to the AST completion 
routine. 

pl not used (omit the argument). 

p2 address of a quadword descriptor of a counted string of 


optional user data. Both the string and its descriptor 
must be in read/write storage. 


Return Status 


SS$ NORMAL The service completed successfully. 
SS$_FILNOTACC No logical link is associated with the 
channel. 


7.8.10 $QIO (Declaring a Network Name or Object Number) 


The S$QIO system service with a function code of I0$ ACPCONTROL assigns 
a network name or object number to the task, thereby making it 
eligible to process multiple inbound connection requests. You must 
associate a mailbox with the I/O channel. All inbound connection 
requests are placed in the mailbox associated with the channel over 
which this I/O function is issued. The SYSNAM privilege is required 
to declare a name or object number. 


MACRO programmers should be aware that whenever a logical link is 
established, its device unit number (for example, 18 from NET18:) 
should be obtained by using the $GETDVI system service, because unit 
numbers and not channel numbers appear in mailbox messages. Use this 
system service call where a single mailbox is being used for many 
logical links. The unit number could be used as a key into a data 
base which keeps track of multiple links. 


Format 


SQIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,pl ,p2 


Arguments 
efn number of the event flag to be set at event completion. 
chan a word containing the channel number associated with 
the logical link. Use the same channel number assigned 
previously in the SASSIGN call. 
func IO$  ACPCONTROL 
iosb address of a quadword I/0 status block that will 


receive the completion status. 
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astadr entry point address of the AST routine that executes 
when the I/O operation completes. If specified, the 
AST routine executes at the access mode from which the 

SQIO service was requested. 


astprm the AST parameter to be passed to the AST completion 
routine, 


pl address of a quadword descriptor of a 5-byte block 

: consisting of a function type (one byte) and a longword 
parameter. The function type is a symbol defined. by 
-the S$NFBDEF macro in SYSSLIBRARY:LIB.MLB. The format 
of the 5-byte block for declaring a name is: 


-BYTE NFBSC_DECLNAME 
- LONG 0 


The format of the 5-byte block for declaring an object 
number is: 


- BYTE NFBSC_DECLOBJ 
- LONG object-number 


where the object number is a number’ reserved for 
customer use in the range of 128 to 255. This 5-byte 
buffer and its descriptor should be in read/write 
storage. 


p2 address of a quadword descriptor of the network name 
(maximum of 12 characters). This is ignored for the 
DECLOBJ function. Both the name and its descriptor 
must be in read/write storage. 


Return Status 


SS$_NORMAL The service completed successfully. 

SS$_BADPARAM One of the QIO parameters has an invalid 
value. 

SS$_ILLCNTRFUNC The control function is invalid. 

SS$_NOMBX A name or object number is being declared 
using a channel without an associated 
mailbox. 

SS$_NOPRIV The issuing process does not have the SYSNAM 


privilege. 


7.8.11 S$DASSGN (Terminating a Logical Link) 


The SDASSGN system service terminates all pending operations to send 
and receive data, aborts the logical link immediately, and frees the 
channel associated with that link. Refer to Section 6.7.6 for the 
format of this call, it arguments, and possible return status codes. 


7.9 PROGRAMMING EXAMPLE FOR NONTRANSPARENT COMMUNICATION 


Example 7-1 illustrates the use of several of these system service 
calls for nontransparent task-to-task communication. CONNECT is a 
nontransparent MACRO source task on the local node that communicates 
with a nontransparent target task, DECLARNAM, on node DENVER. This 
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example is similar to Example 6-1, except that here the source task 
uses an NCB and performs a nontransparent assign operation to 
establish communication with the target’ task. DECLARNAM is a 
nontransparent target task that has declared a name (that is, it is 


eligible to receive multiple inbound connection requests). In 
addition, it also uses a mailbox to receive network status 
notifications. Neither task performs useful functions. They are 


presented here only to illustrate various nontransparent functions. 


Example 7-1: Nontransparent Task-to-Task Communication 
Using System Services 


DECLARNAM 


*TITLE DECLARNAM- NONTRANSFARENT EXAMPLE (WITH DECLARED NAME) 
IDENT /¥1.0/ 

*SETTL REATONLY_DATA 

*FSECT TDECLARNAMEREDATA SHR»NOEXE » RItyNOWRT> BYTE 


$NFBDEF 
$0 TBUEF 


Fseudo-device & descrirtor 
Maximum messasde size 
Euffer auotea 
Mailbox logsmam & descrirtor 
Maximum #€ of lodicsl links sllowed 
Size of inrut buffer to #eccert 

; Messastes 


DEVGHESC?.,ASCIT /_NETi/ 
MAXMSG: .LONG 128 

BUF QUO’ «LONG 128 
MEXDESC: .ASCIN /DECLARMEX/ 
MAXLINKS=128 

BUFFER JSIZE=464 


o> we eh ee nee see 


+SETTL READWRITE_DATA 


»FSECT TECLARNAM#RWIATA SHR »+NOEXE sR WRT BYTE 
NAMEDESC? + Declared name & descrirtor 
»~-ASCIED /TECLAR/ 
ICL CHAN? 
»>BLKW 1 5 Word to receive declared name chan # 
TEV CHAN? 
e BLKW 1 3 Word to receive device channel #¥ 
MBX CHAN? 
»>BLKW i Word to receive mgzilbox channel # 


Mailbox tuffer 
I/O status black 
I/0 status block for AST 


MEXMSG? .BLKB 128 
IOSB? + BLKQ i 
AST_IOSB? 

+BLKQ i 
NCRDESC?.LONG 100 

+LONG NCE 
NCE? +BLKE 100 
NFBRRESC? LONG o 

«LONG NFR 
NF ES +BYTE NFRSC_TECLNAME 

+LONG 0 
FRILEN? .WORD Q 
FRIBUF? «LONG 128 

+LONG P RUF 
PRUF? +BLEB 128 
COUNTS «BLKL 1 
CHAN_LIST? 

+BLRW MAXLINKS 
UNITOLIST? 

+BLRW MAXLINKS 
IOSEK_LIST: 

+BLKQ MAXLINKS 
BUFFERS’. BLKE MAXLINKS &* BUFFER.SIZE 


Se en oe Td 


Network control block descriptor 


“es 


Network control block 
Network function block descrirtor 


Pr ae 


Network function black 


Pd 


Lensth of buffer for #GETCHAN info 
Descrirstor of @¢GETCHAN buffer 


ar see 


Ruffer to receive $GETCHAN info 
Count of # of table entries 
Channel # list 


a 


Unit # list 


“a 


Read messsde I/0 status bhlock list 


“> 


Ineut buffers to rut messages 


“er 
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BUF_LADROLIST? 3 List of Pointers to input buffers 
QFFSET = 0 
REPT MAXLINKS 
*ANTRESS BUFFERS + OFFSET 
QFFSET = OFFSET + BUFFERLUSIZE 
eENDIR 


oSBTTL MAIN 


fb 
5 
§ This vrrogdran demonstrates the use of a declared name to sallow multirle 
' inbecund conmmection reauests., It is included for illustrative rurroses 
f and is mot intended to rerform any useful work, In rarticulary nonnetwork 
§ code is khert to a minimum ( mote for exameley that all errors result in 
> rrogrem terminatian ~ en ingerrarriate rrocedure for most arrlications), 
, 

*+PSECT TECLARNANECORE NOSHR EXE sRIyNOWRTS BYTE 

*ENTRY START s “Mth | 5 Main entry Faint 


Create 3a temrorary mailbox with the losical mame DECLARMBX, 


sae ote owe 


$CREMBA_LS ~- 
CHAN=W° MEX CHAN» - 
MAXMSG=W"°MAXMSG ¢ - 
BUF QUQ=W7 BUF QUO» —- 
LOGNAM=W°MEBXDESC 


Adr of word to Fut mailbox channel 
Adr of lonsword with max messesde size 
Adr of londword with buffer auotea 

Adr of descrirtor of mix lognam 


“> a> ep “eo 


BLEC ROr,EXITS + Error if LEC 


sisnm & chennel to 3 NET device end associate the mailbox with it. 


“> Ne SOP 
> 
wt 
Pa 
w 
if 


PASSIGN_LS - 
NEVNAM=W°DEVDESC s- 
CHAN=W°DCL CHAN » - 
HEXNAM=W"MBXDESC 


Issue $ASSIGN system service reauest 
Adr of descrirstor of NET device 

Adr of word to rut channel ¥ 

Adr of descrirtor of mox lognam 


eh eb ae oe 


> 


RLEC ROsEXITS Error if LBC 


“ 


feclare s network name, 


say “te tae 


Issue declare name reauest 

Use assisned channel 

ACF QI0 

Adr of I/70 status block 

Adr of NFE descrirtor 

Adr of declared name descrirtor 


#QTOWlgs - 
CHAN=WCDCL CHAN »— 
FUNC=#1T0¢ ACFCONTROL > - 
LTOSK=W"LTOSE,- 
PISW°NFEDESC > - 
P2=#NAMEDESC 


sap wr Sah er sae > 


BLEC ROsEXITS + Error if LEC 
MOVZWL W°ITOSBs RO § Get the I/0 status 
BLEC ROsEXITS * Error if LEC 


; 
§’ Issue an asyumchronous read to the mailbox. 
rf 
BSEW REATILMEX + Set ur mailbox read AST 


Nows go to sleer until someone writes to our mailbox. 


“er ~c> wor 


$HIBER_S § ZASASSTErerrveve 
EXITS: #EXIT_S RO 5 Exit with status 


+SETTL MAILEBOX_AST 
*ENTRY MAILBOX_AST?"Me> 5 Entry roint for AST. routine 
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+ 


> “ee cP ser 
2 


and determine the 
MOVZWL 
BLEC 
CASEB 
DISFITAB? 
»WORT 
WORD 
«WORT 
eWORT 
«WORT 
»wORT 
»WORT 
WORT 
WORD 
»WORL 
WORT 
HORT 
ERE 
CONNECT? 
; BSEW 
CMEW 
BEQL 
BSEW 
1043 BSEE 
RET 
DISCON: 
AKRORT? 
EXIT? 
FATHLOST? 
FROTOCOL ¢ 
YHIRDFARTY? 
TIMEQUT: 
BSEW 
BSEE 
RET 
NETSHUT?: 
#WAKE_S 
RET 
INTMSG: 
REJECT? 
CONFIRM: 
RSEB 
RET 
~SETTL 
+ENTRY 
+ 


‘cP ah > var 


MOVL 
MOVQ 
CMPW 
BEQL 
ELEC 


AST routine to examine the mailbox 


AST routine to check the comrletion 
the message received. 


message code 
BFFrorrisate ection, 


W°AST_IOSEs RO 


§ get asunc I/0 completion 
ROrEXITS 3 


status 
Branch on failure ; 


W°MEXMSGs €MSG¢_ABORTs €MSG¢_NETSHUT~MSG$_ABORT 


ABORT-IISF_TAB 
CONFIRM-DISF_TAB 
CONNECT-RISF_TAB 
DISCON-DISF_TAE 
EXIT-LISF_TAB 
INTMSG-UISF_TAB 
FATHLOST-DISFOTAB 
FROTOCOL-DISP_TAB 
RE JECT-DISFOTARB 
THIRDFPARTY-DISF_TAB 
TIMEOQUT-DISFLUTAB 
NETSHUT-DISFLTARB 
Fall through on mbxms# out of 


“ay ‘er 


SERVICES 


range 


EXITS Unknown mailbox message encountered 
CONNECT UACCEFPT > Go accert the connect reauest 
#FIO¢_ACCESS!IOSM_ABORT,* R43 Was the conmect request rejected? 
104 > If reviected then do mot issue the 
; read 
READ UCHAN > Issue @ read om the channel we 
3 Just confirmed 
READ MEX + Reaueue the msilbox read AST 
> Return control to maim rrogram 
DISCONNECT 5 Go disconnect the link 
READ_LMEBX + Reaueuvue the mailbox read AST 
5 Return control to main 
+ The network is shutting down 
> Weke the main Frodgram so that 
3 it will exit 
> Ignore interrurt messages for 
§ this example 
REAL MBX § Reaueue the mailbox read AST 
5 Return control to main 
READ_LAST 
REALLAST s+ "Ma § Entry roint for AST routine 


status of the read and to rrocess 


4 (AF) sRS8 
W°ITOSK_LISTECRSI*RO 
#SS$_LINKABORT s+ RO 
10% 

ROrEXITS 


Get the index to the lists 
Get the I/0 completion status 
Tid the link go away? 

If EQL then ignore 

If LEC then error 


> ‘a> ee sem sar 


<> “er em wee o> wor 
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OKs we have received a message and written it into the buffer rointed 
to oy BUFLADR LISTOCRII, Useful code could be inserted here to rrocess 
the message, When comrlete,y we reissue the read on the channel and 
then do oback to where we were interrurted,. 


MOVU WCCHANLLISTCR8I+R3 + Get the channel number 
BSEE READ_CHAN 5 Reissue the read 
1083 RET $ Return from AST routine 


! 
4 
y 
a 
, 


*SETTL SUBROUTINES 


a 4. 


Subroutine ta issue an asynchronous read to the mailbox with an AST. 


READLMBX $ 


#QI0_S - §' Issue read with AST 
CHAN=WC MBX CHAN »- 5 Use assigned msilhbox channel 
FUNC=#TO$  READYVELK » - 5 Read virtual block 
TOSK=W"AST_IOSE:- > Address of I/0 status block 
ASTADR=W°MATILEOX_AST+s—- §' Address of AST routine 
Fi=W°MEXMSG?- } Address of inrut buffer 
FQ=W°MAXMSG s Lensth of inrut buffer 

BLES ROv LOE * Error if LEC 

BRW EXITS + Branch (failure) 

10: RSE § Return from subroutine 


sm> ser “a> 


+ 
Subroutine to issue an asynchronous reed to the channel with an AST. 


READLCHANS 


$€QI0_S ~- j Issue read with AST 
CHAN=RSs- + Use channel we Just confirmed 
FUNC=#ITO$ READVBEL Ky — + Reed virtual block 
LTOSR=WTIOSBLLISTCRSIJ:- § Address of I1/0 status block 
ASTADIR=W"READLAST+~- + Address of AST routine 
ASTFPRM=R8-- 5 Store index as AST rarameter 
PL SEWU°BUPLADR LISTERS Is~- ¢ Address of inreut ouffer 
PO2=r#BUFFER_LSIZE > Length of inrut buffer 

BLES RO»10¢ + Error if LEC 

ERW EXITS 5 Branch (failure) 

103 RSE ' Return from subroutine 
+FAGE 


ee ee Nee 


+ 
Subroutine to accert the connect reauest and edd the channel and unit 
nmumoers to the lists 


go 


CONNECT_ACCEFT? 


es cm <> 


MOVAER W°MEXMSG+49RF 
MOVZEL (CRO) +teRS 
ANTIL2 R32R9 

MOVZBL (R99) t*RE 
MOVCZ R82 (RD) sWONCE 
MOVL RS, W°NCRRESC 


Get adr of device name count 

Get byte count of device name string 
Shir over the string 

Get byte count of info strings 

Fut the NCB in adr NCE 

Urdate the NCB descriretor 


ar > “a> wee er se 


Make sure we haven’t reached maximum links. 


CMPL #EMAXLINKS WT COUNT + Have we reached max # of links? 
BRGTR S$ > No? then so assidnm 8 channel to NET 
MOVW W°DCLOCHAN®S RS § Use the orisginal channel 


MOVZWL #IO$ ACCESS! IOSM_ABORTsR45Seture with conmect reject func code 
BRE 25% § Go make the reJject 


$3 


a] 


Nowy 


Bo or owe oD 


$y 


Issue 


net Ate 


2582 


SOEs 


HOES 


+ 


ah ah ae 
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SASSIGN. 


BLES 
BRW 


get the 


$GETCHN_ 


ELES 
BRW 


CLRL 
TSTW 
KREQL 
ADELEQ 
BRW 


MOV 
NQVwW 
INCL 


the connect 


MOVU 
MOVZWL 
€QTOW_s 


ELES 
ERW 
MOVZWL 
ELES 
BRYW 
RoE 


Subroutine toa 


LISCONNECT? 


tn 
pa 
a 
ord 


1033 


MOVZWL 
CLRL 
CHEW 
BEQL 
AQKLER 
MOVZWL 


$0ASSGN_ 


BLES 
BRRW 


channel 


S - 
DEVNAM=WTTEVDESC »- 
CHAN=U7DEV_CHAN®? - 
MEXNAM=W°MEXTESC 
RO»10% 

EXITS 


and 


S - 
CHAN=W°TEY. CHAN? - 
PRILEN=W"FRILENs- 
FRIEUF=WCPRIBUF 
ROs194¢ 

EXITS 


R8 
W°CHAN_LISTCRS8] 
22¢ 
W°COUNTs R22 208 
EXITS 


WOKEV CHANsW°CHAN_LLISTCRE 15 Put the chan 
W°FRUFTOIBEW UNIT» WCUNITULISTCRSI3 


W°COUNT 


confirm QIO0. 
WUTEV_ CHAN SRS 
5S“#IQé_ACCESS:+kR4 
CHAN=R3+- 
FUNC=R43- 
TOSR=W°IOSE:s- 
PO=#€NCBIESC 


RO? 308 
EXITS 
W°TOSE?sRO 
RO» 40¢ 
EXITS 


discanmnmect 3 channel 


W°MEXMSG+22RO 

R8 
WCUNTITOLISTOR8I] KO 
10% 

W°COUNT s R825 
W°CHAN_LISTCRSI°R9 
S - 

CHAN=R9 

RO» 20¢ 

EXITS 


unit numbers 


“a> er “Oe “a> see ‘er 


i ey 


<a> sep wep wae wee 


s 
’ 


Oe eC 


Ot oT 


and 


sah Om er ee Sem ee ner “ee ee ee 


and rut them 


Assign a@ channel to the task 
Adr of NET descrirtor 
Channel * 

Associate the mailbox 
If LBC then error 
Branch (failure) 


with new net dev 


im their resrective lists. 
Issue set chan sustem service 

Adgr of word containing channel # 
Adroaof word to rut length returned 
Adr of descrirtor of buffer 

If LEC ther error 

Branch (feilure) 


Initialize the index 

Is it emety? 

Branch if we found an emrty slat 
Ine the index and try again 

No empty slots? 


list 
list 


# in the chan 
Fut unit # in unit 
Increment the # of entries 


Set ur with edr of assigned chan 
Setup with conmmect seccert func code 
Issue connect confirm/reiject reauest 
Use assigned channel 

Request a logical link 

Address of 1/70 status block 

Address of NCE descrirtor 


If LEC then error 
Eranch (failure) 
Get I/O comrletion 
If LBC then error 
Branen (failure) 
Return from subroutine 


status 


remove its entry from the lists. 


Get the unit # 
Initialize the index 
Locate the unit # in 
If EQL then success 
Ine the index and try asain 
OKs we’ve dot the channel +# 
Tleassign the channel 
Channel # 

If LEC then error 

Branch (failure) 


the list 
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3 
¢ ORs the channel has peen deassigned. Remove the entries from the unit and 
> channel Lists. 
; 
ROR 
QECL W°COUNT i Tecrement the # of entries 
CLAW W°CHAN_LISTCRS] 5 Clear the chan list entry 
CLAW W°UNITULISTCRSI $ Clear the unit list entry 
RSE > Return from subroutine 
*ENT START i Image transfer address 
CONNECT 
+TITLE CONNECT - ISSUE A CONNECT REQUEST TO DECLAR (CTRECLARED NAME) 
»>SETTL READONLY_DATA ‘ 
*PSECT CONNECTERIDATA SHR»+NOEXEsRDyNOWRTs BYTE 
MEVGDESCS .ASCIO /_NETIZ 5 Pseudo-device & descrirtor 
MAXMSG: .LONG 64 *; Largest size mailbox message allowed 
BRUFQUO? «LONG &4 * Maildoex auots 
»SETTL READWRITE_DATA 
*FSECT CONNECTSRWIATA SHR»eNOEXEs RE SWRTs BYTE 
QEY CHAN? 
sRLKW 1 s+ Word to receive device channel # 
MBX CHAN? ; 
eRLKW 1 5 Word to receive mailbox channel # 
MEXMSG! .BLKB 54 ’ Mailbox ouffer 
IOSE? +BLEQ 1 + I/O status block 
NCBDESC?:.LONG NCB_USIZE + Network conmect block & descrirtor 
«LONG NCE 
NCR sASCII THENVER? i? + Node-srec string 
*-ASCII ?°TASK=DECLAR/? 3 Task-serec string (declared name) 
»WORT i) $ Must be zero. 
sASCIIO /*/ ' End of NCB 
NCELSIZE=,.-NCR > Size of NCE 
+SBETTL MAIN 


+ 


declared a network 
does serve to illustreéete 


which has 
out 


Mawes 


er scr ee a> “er 


»FSECT 
+ENTRY 


CONNECTSCOLE 
START s "Mas 


+ 

Use the 
8 communication 
nantrensrarent I/Q orerations, 


func-time library routines 


This routine will? 


1. Create s temerorary mailbox 
a channel to NET? 


with it, 


2. Assign 
mailbox 


The mailbox can be used to obtain 


we 


<a> wee “er cm em er Ge > wee “to oe er ed scr “ae 


This Fragram demonstrates how to make a canmection 
It does not rerform 
RECnet nontransrarent I/0, 


rath to DECnet software in 


and assign 


request to a task 
any useful work 


NOSHRs EXE» REyNOWRTs BYTE 


LIBSASN_WTHOMBX to establish .- 


Freraration for 


3 channel to it. 


and associate the temrorary 


surrlementary information from 
NECnet software sabout lodical link orerations. 
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FUSHAW W°MBX CHAN 

FUSHAW W°TEV CHAN 

FUSHAL W"RUFQUO 

FUSHAL W°MAXMSG 

PUSHAQ W°DEVDESC 

CALLS #5 »LIBSaSn_WTH MEX 


ee er ab ee ee ee ee ee 


BLES RO,10% 
BRU EXITS 
F : 
+ Reauest @ logical link to the remote tea 
3 
10% $€QIOW_S - ; 
CHAN=W°DEV_CHAN?- ; 
FUNC=4#I0¢_ACCESS:- 3 
ITOSB=W° LOSE: - ; 
Po=€#NCRDESC 3 
BLEC ROrEXITS $ 
MOYVZWUL W7ITOSB,RO , 
ELEC ROrEXITS ; 


We maw have a logical link with TDECLARN 
here before continuing with the disconn 


Sh otap see Ser 


¢ ORs mow disconmect the logical link fy 


$DASSGN_LS - 
CHAN=U°DEVCHAN 
BLEC ROYEXITS 


1 


EXITS! #EXIT_S RO ; 


+END START 


COMMUNICATION USING SYSTEM SERVICES 


Adr to receive mailbox channel #* 

Adr to receive device channel # 
Mailbox auota 

Largest size mailbox message allowed 
Adr of device name descriFrtor 

Assign channel & associate mailbox 
If LBC then error 

Kranch (failure> 


sks 


Issue connmect initiate reauest 
Use assigned chennel 

Reauest a logical lirk 

Address of I/0 status block 
fddress of NCE descrirtor 


If LEC then error 
Get I/O completion status 
If LEC then error 


AM, Useful code could be inserted 
ect. 


deassidning the channel. 


Issue the deassign reauest 
Adr of word containing channel + 
If LEC then error 


Exit with status to be disrlaved 


a 


} on error condition 


APPENDIX A 


OBJECT TYPE CODE VALUES 


Table A-1 defines valid object type code values and describes’ their 
use for task-to-task communication. All values are expressed in 


decimal. 
Table A-1l: Object Type Codes 


Object Type Description 
Mnemonic 
User program 
Reserved for DIGITAL use 


File Access Listener for remote file 
and record access 


Host loader for RSX-11S down-line 
task loading requests 


“Network Management Listener object 


Reserved for DIGITAL use 
REMACP Network terminal handler (host side) 
Reserved for DIGITAL use 
MIRROR Loopback mirror 
EVL Event receiver 
MAIL VAX/VMS mail facility 
Reserved for DIGITAL use 
VAX/VMS phone facility 
Reserved for DIGITAL use 
63 DECnet Test Receiver object 
64-127 Reserved for DIGITAL use 


128-255 Reserved for customer use. 





APPENDIX B 


VAX-11 RMS CONTROL BLOCK USE 


This appendix identifies which RMS control block fields are used by 
the network routines embedded in VAX-11 RMS when performing network 
file access and task-to-task operations. When both the source and 
target nodes are running VAX/VMS Version 3.0, most of the RMS control 
block fields are supported. The fields that are not used fall _ into 
two general categories: . those. that are ignored and those that are 
treated as an error condition if an unsupported value or bit option is 
specified. When the source node is running VAX/VMS in a heterogeneous 
network, certain fields of the FAB and RAB control blocks, and even 
entire XAB control blocks, may be ignored if they are not supported by 
the target node. 


The general level of support provided by VAX-11 RMS and FAL for a 
given pair of nodes is determined dynamically by an exchange of 
information between them during a DAP setup Sequence. The exact level 
of support, however, sometimes cannot be determined until the function 
is requested, as the remote FAL may return an error in response to a 
value or option it does not recognize or cannot process. 


Tables B-1 through B-10 describe the support status of the fields in 
the FAB, RAB, NAM, and XAB blocks. The following key explains the 
support categories indicated in the tables: 


| KEY | Support Category For Field Value Or Bit Option 


Supported; RMS at the source node will request’ that 
FAL at the target node perform the operation as 
specified. 











Supported if 
to perform 
ignored (not 


the target node uses VAX-11 RMS or RMS-11 
its file operations; if not, the field is 
used as an input: or output). 















Supported if the target node uses VAX-11 RMS to perform 
its file operations; if not, the field is ignored (not 
used as an input or output). 










Not supported; the field is ignored (not used as an 
input or output). 










Not supported; «an RMS$ SUPPORT error is returned. 


Not applicable; the field is. not a user input or 
output. 





Note that the comment “used locally" means that the bit option is 
input to VAX-11 RMS processing.at the source node, but is not sent to 
FAL at the target node. 


VAX-11 RMS CONTROL BLOCK USE 


Table B-l: FAB (File Access Block) 


FABSL_ALQ Allocation quantity 


FABS$B_ BID Block identifier Static field 


FABSB_BKS Bucket size 
FABSB_BLN Block length Static field 


FABSB_BLS Block size 


PABSL_CTX 


FABSW_DEQ 


FABSL_DEV 


FABSL_DNA 


FABSB_DNS 


User context 


Default file extension 
quantity 


Device characteristics 


Default file specification 
string address 


Default file specification 
string size 


File access options 


FAB$B_FAC 


FABSV_BIO 
FABSV_BRO 
FABSV_DEL 
FABSV_GET 
FABSV_PUT 
FABSV_TRN 


FABSV_UPD 


Block I/O operations 
Record I/0 operations 
SDELETE operations 

SGET and S$FIND operations 
SPUT operations 

STRUNCATE operations 


SUPDATE operations 


Output only field* 


Listed by subfield 


Used with RABSV_BIO 


FABSL_FNA File specification string 
. address 


FAB$B_ FNS File specification string 
size 


FABSL_FOP File processing options Listed by subfield 
FABSV_CBT Contiguous best try 
FABSV_CIF Create if nonexistent 


FABSV_CTG Contiguous allocation 





*This reflects the actual characteristics of the target device, if the 
remote node uses VAX/VMS and the RMS operation is $CREATE or SOPEN. It is 
not valid for a $PARSE call. 


(continued on next page) 


VAX-11 RMS CONTROL BLOCK USE 


Table B-1 (Cont.): FAB (File Access Block) 


FABSV_DFW Deferred write 
FABSV_DLT Delete file on close 
FABSV_MXV Maximize version number 
FABSV_NAM Use name block 


FABSV_NEF Do not position at 
end-of-file 


FABSV_NFS Non file structured 

FABSV_OFP Output file parse Used locally 
FABSV_POS Current position 

FABSV_RCK Read check 

FABSV_RWC Rewind file on close 

FABSV_RWO Rewind file on open 

FABSV_SCF Submit command file 

FABSV_SPL Spool file to printer 


FABSV_SQO Sequential only (enter See Section 4.5.3 
DAP file transfer mode) 


FABSV_SUP Supersede existing file 


FABSV_TEF Truncate at end-of-file 


FABSV_TMD Temporary marked for 
delete 


FABSV_TMP Temporary file 

FABSV_UFO User file open 

FABSV_WCK Write check 

FABSB_FSZ Fixed control area size 

FABSW_GBC Global Buffer Count 

FABSW_IFI Internal file identifier For internal use 
FABSL_MRN Maximum record number 


FABSL_MRS Maximum record size 


FABSL_ NAM Name block address Most fields of NAM 
~ block are used 





(continued on next page) 


FAB$B_ORG 
FABS$C_IDX 
FABS$C_REL 
FABSC_SEQ 

FABSB_RAT 


FABSV_BLK 
FABSV_CR 


FABSV_FTN 

FABSV_PRN 
FAB$B_RFM 

FABS$C_FIX 


FAB$C_STM 


FABSC_STMCR 


FABSC_STMLF 


FABSC_VAR 


FABSC_VFC 


FAB$C_UDF 


FABSB_RTV 


FABSL_SDC 


FABSB_SHR 
FABS$V_DEL 
FABSV_GET 


FABSV_MSE 


FABSV_NIL 


FABSV_PUT 


Table B-1l (Cont.): 


VAX-11 RMS CONTROL BLOCK USE 


File organization 
Indexed 
Relative 
Sequential 

Record attributes 


Records do not cross 
block boundaries 


Implied carriage control 


(LF <record> CR) 


FORTRAN carriage control 


Print file format 
Record format 
Fixed length 


Stream with LF, FF, VT 


and CRLF terminator set 


Stream with CR record 
terminator 


Stream with LF record 
terminator 


Variable length 


Variable length with 
fixed control 


Undefined 
Retrieval window size 


Spooling device 
characteristics 


File sharing options 
Allow other DELETEs 
Allow other GETs 


Multistream access 
enabled 


Prohibit file sharing 


Allow other PUTs 


FAB (File Access Block) 


Listed by value 


Listed by subfield 


Listed by value 


Same as DEV field 


Listed by subfield 
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VAX~-11 RMS CONTROL BLOCK USE 


Table B-1 (Cont.): FAB (File Access Block) 


FABSV_UPD Allow other UPDATEs 











FABSV_UPI User-provided For block I/0 


interlocking 












FABSL_STS Completion status code Yes Also returned in RO 








FABSL STV Status value Yes Has DAP code when 
me STS=RMS$_SUP, 

STS=RMS$_NET, or 

STS=RMS$_BUG_ DAP 











FABSL_XAB Extended attribute block Yes kk 
address 






**In general, if the remote FAL does not support an extended attribute 
block, the XAB is not used as input or output for the operation. 


Table B-2: RAB (Record Access Block) 


2 ee ee (8 


RABSB | BID Block identifier Static field 


RABSL_BKT Bucket code 

RABSB_ BLN Block length Static field 
RABSL_CTX User context For user 
RABSL_FAB File access block address 

RABSW_ISI Internal stream identifier For internal use 
RABSL_KBF Key buffer address 

RABSB_KRF Key of reference 

RABSB_KSZ Key size 

RABSB_MBC Multiblock count 

RABS$B_MBF Multibuffer count 

RABSL_PBF Prompt buffer address 

RABSB_PSZ Prompt buffer size 

RABSB_RAC Record access mode Listed by value 


RABS$C_KEY Random access by key 
value 
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VAX-11 RMS CONTROL BLOCK USE 


Table B-2 (Cont.): RAB (Record Access Block) 


RABSC_RFA Random access by file 
address of record 


RABSC_SEQ Sequential access 

RABSL_RBF Record buffer address 
RABSW_RFA Record's file address 
RABS$L_RHB Record header buffer 


RABSL_ROP Record processing options Listed by subfield 


RABSV_ASY 
RABSV_BIO 
RABSV_CCO 
RABSV_CVT 
RABSV_EOF 
RABSV_FDL 
RABSV_LOC 


RABSV_KGE 


RABSV_KGT 


RABSV_LIM 


RABSV_LOA 


RABSV_NLK 


RAB$V_NXR 


RABSV_PMT 
RABSV_PTA 
RABS$V_RAH 


RABSV_REA 
RABSV_RLK 


RABS$V_RNE 


RABS$V_RNF 


Asynchronous I/0 


Change to block I/0 


- Cancel control O 


Convert to uppercase 
Position at end-of-file 
Fast record delete 
Locate mode 


Key is greater than or 
equal to 


Key is greater than 
Test for key limit 


Load buckets via fill 
size 


Do not lock record 


Nonexistent record 
processing 


Prompt on read 
Purge type-ahead buffer 
Read ahead 


Lock record for read, 
allowing other readers 


Lock record for write, 
allowing other readers 


Read no echo 


Read no filter 





Used locally 


Used with FABSV_BRO 
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Table B-2 (Cont.): RAB (Record Access Block) 


<2 ee |. 


RABSV_RRL 
RABSV_TMO 
RABSV_TPT 


RABSV_UIF 


RABSV_ULK 


RABSV_WAT 


RABS$V_WBH 
RABSW_RSZ 
RABSL_STS 


RABSL_STV 


RAB$B_TMO 
RABSL_UBF 


RABSW_USZ 





NAM$B_BID 
NAMS$B_BLN 
NAMSB_DEV 


NAMSL_DEV 


NAM$W_DID 


NAM$B_DIR 
NAMSL_DIR 


NAM$T_DVI 





Read regardless of lock 
Enable timeout 

Truncate put 

Update if 


Enable manual record 
unlocking 


Wait until record 
unlocked 


Write behind 
Record size 


Completion status code Also returned in RO 


Has DAP code when 
STS=RMSS SUP, 

STS=RMSS$ NET, or 
STS=RMS$ BUG DAP 


Status value 


Timeout period 
User record area address 


User record area size 


Table B-3: NAM (Name Block) 


Block identifier Static field 


Block length Static field 
Device string length 

Device string address 

Directory identification Zeroed on output 
Directory string length 
Directory string address 
Device identification Zeroed on output 
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Table B-3 (Cont.): NAM (Name Block) 


NAMSL_ ESA Expanded string area 
address 


NAMSB_ESL Expanded string length Output only field 
NAMS$B_ESS Expanded string area size 
NAMSW_FID File identification Zeroed on output 
NAMSL FNB File name status bits Except for 

a NAMSV_HIGHVER and 

NAMSV_LOWVER 

NAMSB_NAME File name string length 
NAMSL_NAME File name string address 
NAMSB_NODE Node name string length 


NAMSL_NODE Node name string address 


NAMSL_RLF Related file NAM block 
address 


NAMSL_RSA Resultant string 
address 


NAMSB_RSL Resultant string length Output only field* 


NAMSB_RSS Resultant string area size 
NAMSB_TYPE File type string length 
NAMSL_ TYPE File type string address 
NAMSB_VER File version string length 


NAMSL_VER File version string 
address 


NAMSL_WCC Wild card context For internal use 





*If the remote FAL does not support the ‘return of a resultant name string, 
then a copy of the expanded name string is returned in this field. 


VAX-11 RMS CONTROL BLOCK USE 


Table B-4:  XABALL (Allocation Control XAB) 


XABSB_AID Area identification number 





Alignment boundary type 








XABS$B_ALN Listed by value 









XABSC_CYL Cylinder 


Logical block number 





XAB$C_LBN 






XABSC_RFI Related file No 






XABSC_VBN Virtual block number VAX 






XABSL_ALQ Allocation quantity 








XABSB_AOP Allocation options Listed by subfield 













XAB$V_CBT Contiguous best try 


XABS$V_CTG Contiguous allocation 







XABSV_HRD Hard error VAX 





XAB$V_ONC On cylinder boundary 








XABSB_BKZ Bucket size Yes 








XABSB_ BLN Block length Static field 












XAB$B_COD Type code Static field 





XABSW_DEQ Default extension quantity 







XABS$L_LOC Location VAX 






XABSL_NXT Next XAB address Yes 





Relative volume number 






XABSW_VOL 


VAX-11 RMS CONTROL BLOCK USE 


Table B-5: XABDAT (Date and Time XAB) 


XABSB_BLN Block length Static field 












XAB$Q_BDT Backup date and time Yes 






XAB$Q CDT Creation date and time Yes 






XABSB_COD Type code NA Static field 






XABSQ_ EDT - Expiration date and time Yes 






XABSL_NXT Next XAB address Yes 






XABS$Q_RDT Revision date and time Yes 









XABSW_RVN Revision number Yes 


Table B-6: XABFHC (File Header Characteristics XAB) 


a ae A 


XABSB_ATR Record attributes Output only field 








XAB$B_BKZ — Bucket size Yes Output only field 








XABSB_BLN Block length NA Static field 









XAB$B_COD Type code NA Static field 







XABSW_DXQ Default file extension Yes Output only field 
quantity 






XABSL_EBK End-of-file block Yes Output only field 









XABSW_FFB First free byte in Yes Output only field 


end-of-file block 









XABSW_GBC Global buffer count No Output only field 









XABS$L_HBK 





Highest virtual block Yes Output only field 
in file 










XAB$B_HSZ Fixed length control Yes Output only field 


header size 










XABSW_LRL 





Longest record length Input for SCREATE 





XABSW_MRZ Maximum record size Yes Output only field 






XABSL_NXT Next XAB address Yes 






XAB$B_RFO 






File organization and 
record format 





Output only field 










XABSL_SBN Starting logical block 


number (if contiguous) 





XABSW_VERLIMIT Version limit for file No Output only field 
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Table B-7: XABKEY (Key Definition XAB) 


XABSB BLN © Block length Static field 















XAB$B_COD Type code NA Static field 





XABS$SB_DAN Data bucket area number Yes 









XABSB_DBS Data bucket size Yes Output only field 






XABSW_DFL Data bucket fill size Yes 








Listed by value 









XABS$B_DTP Data type of the key 








XABSC_BN2 Unsigned 2-byte binary 











XABSC_BN4 Unsigned 4-byte binary 


XABSC_IN2 Signed 2-byte integer 






XABSC_IN4 Signed 4-byte integer 






XABSC_PAC Packed decimal Yes 





XABSC_STG String Yes 








XABSL_DVB First data bucket start Yes Output only field 
virtual block number 










Key options flag Listed by subfield 





XAB$B_FLG 








XABSV_CHG Can be changed Yes Alternate key only 













XABSV_DAT NCMPR Do not compress data No 





XABSV_DUP Can be duplicate Yes 











XABSV_IDX_NCMPR Do not compress index No 






XABSV_KEY NCMPR Do not compress key No 








XABSV_NUL Null key value Yes Alternate key only 











XABSB_IAN Index bucket area number 









XABSB_IBS Index bucket size Yes Output only field 









XABSW_IFL Index bucket file size Yes 









XABSL_KNM Key name address 





XAB$B_LAN Lowest level of index area Yes 
number 










XABSB_LVL Level of root buckets Yes Output only field 











XABSW_MRL Minimum record length Yes Output only field 










XABSB_NSG Number of key segments Yes Output only field 





(continued on next page) 


VAX~11 RMS CONTROL BLOCK USE 


Table B-7 (Cont.): XABKEY (Key Definition XAB) 


XABS$B_NUL Null key value 
XABSL_NXT Next XAB address 
XABSW POSO Key position 
through 
XABSW_POS7 
XAB$B_PROLOG Prolog level Primary key only 
XABSB_REF Key of reference 


XABS$L_RVB Root index bucket start Output only field 
virtual block number 


XABSB_SIZ0 Key size 
through 
XAB$B_SIZ7 


XAB$B_TKS Total key size Output only field 





Table B-8: XABPRO (File Protection XAB) 


XAB$B_BLN Block length Static field 










XAB$B_COD Type code NA Static field 


Group number of file owner 









XABSW_GRP See XABSL_UIC* 





XABSW_MBM Member number of file Yes See XABSL_UIC* 
owner 










-XABSB_MTACC Magnetic tape accessibility 






XABSL_NXT Next XAB address Yes 





XABSW_PRO File protection 








XABSL_UIC User identification code Yes * 
(contains group and member 
number subfields) 







*Zero is returned if the target node uses a non-VAX/VMS syntax to express 
the group and member UIC fields. 
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Table B-9: XABRDT (Revision Date and Time XAB) 


XABSB_BLN: Block length Static field 
XABSB_ COD Type code . Static field 


XABSL_NXT Next XAB address 


XABSQ. RDT Revision date and time 


XABSW_RVN Revision number 





Table B-10: XABSUM (Summary XAB) 


XABSB_BLN Block length Static field 










XABSB_COD Type code NA Static field 





XAB$B_NOA.~ Number of allocation areas Yes Output only field 
defined for file 












XABSB_NOK Number of keys defined Yes Output only field 


for file 






XABSL_ NXT Next. XAB address 











XABSW_PVN Prologue version number Yes Output only field 





APPENDIX C 


SUMMARY OF NETWORK SYSTEM SERVICE ERROR MESSAGES 


Table C-1 describes the system service error messages for task-to-task 
communications. 


Table C-l: System Services Error Message Summary 


| messese | teaming 


SS$_ ABORT 
SS$ BADPARAM 


SS$_ CANCEL 


SS$ CONNECFAIL 
SS$_DATAOVERUN 


SS$ DEVALLOC 


SS$_DEVOFFLINE 


SS$ EXQUOTA 


SS$ FILALRACC 


SS$_FILNOTACC 


SSS$_ILLCNTRFUNC 


SS$_INSFMEM 


SS$_IVCHAN 





The I/O request has been aborted by a S$DASSGN 
or SCANCEL. 


One of the QIO parameters has an invalid 
value. 


The I/O on this channel has been cancelled. 


The connection to a network object timed out 
or failed. 


More bytes were sent than could be received 
in the supplied buffer. 


The process cannot access the logical link 
specified in the NCB because that link is 
intended for another process. 

The physical link is shutting down. 

The process does not have sufficient quota to 
complete the request. Sufficient FILLM and 
BYTLM quotas are required to request or 
confirm a logical link. 

A logical link is already accessed on the 
channel (that is, a previous connect on the 
channel). 


No logical link is associated with the 
channel. 


The control function is invalid. 


There is not enough system dynamic memory to 
complete the request. 


An invalid channel number was specified. 


(continued on next page) 


SUMMARY OF NETWORK SYSTEM SERVICE ERROR MESSAGES 


Table C-l (Cont.): System Services Error Message Summary 


| messaze framing 


SS$_INVLOGIN The access control information was found to 
be invalid at the remote node. 


SS$_IVDEVNAM The NCB or task specifier has an invalid 
format or content. 


SS$ LINKABORT The network partner task aborted the logical 
~ link. 


SS$_LINKDISCON The network partner task disconnected the 
logical link. 


SS$_LINKEXIT The network partner’ task exited before 
confirming the logical link. 


SS$ NOLINKS No logical links are available. The maximum 
~ number of logical links as set for the 
executor MAXIMUM LINKS parameter was 

exceeded. 


SS$_NOMBX A name or object number is being declared 
using a channel without an associated 
mailbox. 


SSS _NOPRIV The issuing task does not have the required 
privileges to create a logical link to the 
designated target; or it does not have 


NETMBX and is assigning NET:; or it does 
not have SYSNAM and is declaring a name or 
object number. 


SS$_NORMAL The service completed successfully. 


SS$ NOSOLICIT DECnet could not accept an interrupt message 
at this time. 


SS$_NOSUCHDEV The network device is not loaded (for 
example, the DECnet-VAX software is not 
running currently on the local node). 


SS$_NOSUCHNODE The specified node is unknown. 


SS$_NOSUCHOBJ The network object number is unknown at the 
remote node; or for a TASK= connect, the 
named DCL command procedure file cannot be 
found at the remote node. 


SS$_NOSUCHUSER _ The remote node could not recognize the login 
Pe information supplied with the connection 
request. 


SS$_PATHLOST : The path to the network partner task node was 
lost. 


SS$_PROTOCOL A network protocol error occurred. This 
error is most likely due to a network 
software error. 
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Table C-1 (Cont.): System Services Error Message Summary 


| Message 


SS$ REJECT 


SS$ REMOTE 


SS$_REMRSRC 


SS$ SHUT 


SS$_THIRDPARTY 


SS$ TIMEOUT 


SS$_TOOMUCHDATA 


SS$_ UNREACHABLE 


The network object rejected the connection. 


The service successfully completed. (A 
logical link was established with the target 
task.) This status applies only to an ‘SASSIGN 


call for a transparent link. 


The link could not be established due to 
insufficient system resources at the remote 
node. 


The local or remote node is no longer 
accepting connections. 


The logical link connection was terminated by 
a third party (for example, the System 
Manager). 


The task did not respond to the connection 
request within the required time. 


The task specified too much optional or 
interrupt data. 


The remote node is currently unreachable. 





APPENDIX D 


MAILBOX MESSAGE TYPES 


The $MSGDEF macro defines the mailbox messages described in Table D-1l. 
This table defines the message type, its meaning, and any information 
that may accompany the message. 


Table D-l: 


pte | traning | tntormation 


Mailbox Message Summary 


MSGS$_ABORT 
MSG$_ CONFIRM 


MSG$_CONNECT 


MSG$_DISCON 


MSG$_EXIT 


MSG$_INTMSG 


MSG$ NETSHUT 


MSG$ PATHLOST 


MSG$_ PROTOCOL 


MSG$_REJECT 


MSG$_THIRDPARTY 


MSG$_TIMEOUT 


The logical link was aborted. 
The logical link was confirmed. 


The task received an initial 
connection request. 


The logical link was 
disconnected. 


The partner task exited 
without completing 
outstanding I/0 operations. 


Interrupt message 


The network node is going into 
the "Shut" or "Off" state. 


The partner is no longer 
accessible. - 


There is a general NSP problem. 
The logical link was rejected. 


A third party disconnected 
the logical link. 


The connection request 
timed out. 


Optional data 
Optional data 


NCB 


Optional data 


None 


Message 


None 


None 


None 
Optional data 


None 


None 





GLOSSARY 


access control 


The login control that a node exercises over inbound logical link 
connection requests to determine whether or not the link can be 
accepted. 


cooperating tasks 


Two tasks that communicate with each other in a task-to-task 
communication environment. In particular, cooperating tasks must 
agree on optional user data to be passed, how they will send and 
receive messages to ensure that there is one transmit for each 
receive, and which task will disconnect the link. 


disconnect abort 
Nontransparent tasks can deaccess a logical link via a disconnect 
abort operation without deassigning the channel. This form of 


disconnection indicates to the receiver that not all messages 
sent have necessarily been received. 


handshaking sequence 
The exchange of logical link connection information between two 
tasks. This exchange takes place to enable the successful 
completion of a logical. link connection. 


inbound connection 


The term refers to the fact that a task receives logical link 
connection requests. 


interrupt message 
A user-generated message sent "outside" the normal exchange of 
data messages during nontransparent task-to-task communication. 
This usage of the term "interrupt" is contrary to the normal 
usage, which means to designate a software or hardware interrupt 
mechanism. 

local node 
The node at which you are located physically. 

network connect block 


A user-generated data structure used in a nontransparent task to 
identify a remote task and optionally send user data in calls to 
request, accept, or reject a logical link connection. 


network object 
The term refers to any task with a nonzero object type (for 


example, those programs such as FAL and NML that provide generic 
services across a network). 
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GLOSSARY 


network status notifications 
Notifications that provide information about the state of both 
logical and physical links over which two tasks communicate. A 
nontransparent task can use this information to take appropriate 
action under conditions such as third party disconnections and a 
partner's exiting before I/O completion. 

network task 


A nontransparent task that is able to process multiple inbound 
connection requests: that is, it has declared a network name or 
object number. 

nonprivileged 


In DECnet-VAX terminology, this term means no privileges other 
than NETMBX and MTMPMBX, which are the minimum requirements for 
any network activity. 


object type 
A discrete identifier for either a task or DECnet service on a 
remote node. Object type identifiers can either be 0 plus a name 
(alternatively, TASK=name), or nonzero without a name (for 
example, 17= or FAL=). 


outbound connection 


The term refers to the fact that a task sends logical link 
connection requests. 


privileged 


In DECnet-VAX terminology, this term means any user privileges in 
addition to NETMBX and TMPMBX. 


remote node 
Any node other than the one at which you are located in the 
network. (When debugging programs or for operational symmetry, 
however, you can treat the local node like a remote node.) 


source task 


The task that initiates a logical link connection request in a 
task-to-task communication environment. 


synchronous disconnect 


The disconnect that occurs when a nontransparent task can issue a 
call to terminate I/O operations over a logical link without 
deassigning the channel. Thus, the task can use the channel for 
subsequent I/O operations with the same or a different remote 
task. 


target task 


The task that receives and processes a logical link connection 
request in a task-to-task communication environment. 


task 


In this manual, the term refers to an image running in the 
context of a process. 
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task specifier 


Information provided to DECnet-VAX software so that it can 
complete a logical link connection to a remote task. This 
information includes the name of the remote node on which the 
target task runs and the name of the task itself. 
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Access control, 2-1, 2-5, 
5-7 to 5-8 
Configuration Data Base, 2-7 
defaulting to, 2-2, 2-6 
delimiters, 2-3 
explicit definition of, 2-2, 
2-6 
for inbound connection 
requests, 2-5, 2-8 
for outbound connection 
requests, 2-5, 2-8 
implicit definition of, 2-2, 
2-7 
logical-nodename, 2-2 
LOGINOUT image, 2-5, 5-8 
node name, 2-2 
null information, 2-6 
privileges, 2-6 
string format, 2-2 
User Authorization File 
(UAF), 2-5, 5-8 
Account, 
nonprivileged, 2-7 
privileged, 2-7 
ANALYZE/RMS FILE command, 3-7 
APPEND command, 3-8 
ASSIGN command, 3-4 to 3-5 
SASSIGN system service, 6-2, 
. 6-4 . 
format, 6-4, 7-9 
_NET:, 7-9 
nontransparent use of, 7-2 
transparent use of, 6-2 


BACKUP command, 3-8 


SCANCEL system service, 7-8 
Channel, 5-7 
assigning for logical link, 
5-7, 6-4, 7-9 
deassigning, 5-11, 6-3 
_NET:, 7-2 
SCLOSE call, 4-9, 4-12 
CLOSE command, 3-17 
Code, 
object type, A-1 
System service status 
return, 6-3, 7-9 
VAX-11 RMS completion, 4-3 
Command procedure file, 
See DCL command procedure 
Configuration Data Base, 2-7 
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SCONNECT call, 4-9 

CONVERT command, 3-9 

COPY command, 3-8, 3-13 to 
3-14 

SCREATE call, 4-12 

CREATE command, 3-10 

SCREMBX system service, 7-3 


DAP (Data Access Protocol), 
4-1] 
SDASSGN system service, 5-11, 
6-3, 6-7, 7-18 
format, 6-8 
DCL command procedure, 2-4, 
3-14, 3-18, 5-9 
example using SYSSNET, 3-18 
examples using lexical 
functions, 3-18 
for starting object, 2-4, 
5-9 
lexical functions in, 3-15 
submitting remote, 3-14 
DCL (DIGITAL Command Language) 
command, 1-1, 3-1 
command and file qualifiers, 
3-1 
for accessing records, 3-16 
for command procedure 
submission, 3-14 
for file handling, 3-5 
for file operations, 3-2 
for lexical functions, 3-4 
for logical name operations, 
3-2, 3-4 
for record access 
operations, 3-4 
summary, 3-2, 3-6 
DEASSIGN command, 3-4 to 3-5 
Declared name, 
See Task 
Declared number, 
See Task 
DEFINE command, 3-4 to 3-5 
DELETE command, 3-10 
Destination descriptor, 
See NCB (Network Connect 
Block) 
DIFFERENCES command, 3-11 
DIRECTORY command, 3-11 
Disconnect, 5-11 
abort, 5-11, 7-8 
synchronous, 5-11 
SDISCONNECT call, 4-9 
Double colon delimiter, 2-1 
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DTR object code, A-1 
DUMP/RECORDS command, 3-12 


SERASE call, 4-12 

Error message, 
See Message 

Error reporting, 4-3, 6-3, 7-9 
RMS completion codes, 4-3 
System service status, 6-3, 

7-9 
EVL object code, A-1l 


FSFILE ATTRIBUTES lexical 
function, 3-15 to 3-16 
FSPARSE lexical function, 3-16 

FSSEARCH lexical function, 
3-16 
FAB (File Access Block), 4-9, 
B-2 
FAL (File Access Listener), 
4-1 
object code, A-1 
File sharing over network, 
4-13 
File specification, 2-1 
angle brackets, 2-1 
examples, 2-5 
foreign-file-spec, 2-1, 2-3 
full file specification, 
2-1, 2-3 
node name, 2-1 
node-spec, 2-1 
null character, 2-1 
quoted string, 2-1, 2-3 
restrictions on processing, 
4-12 
space character, 2-1 
square brackets, 2-1 
subdirectories, 2-3 
tab character, 2-1 
task-spec-string, 2-1, 2-4 
wild card character, 2-3 
File transfer throughput, 4-12 
DAP file transfer mode 
(FTM), 4-12 
DAP record access mode 
(RAM), 4-12 
FOP option, 4-12 
FOP disposition options, 4-12 
Foreign-file-spec, 
See File specification 
Full file specification, 
See File specification 
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SGETDVI system service, 7-9 


Handshaking sequence, 
See Logical link 
HLD object code, A-1 


Interrupt message, 
See Message 


LEF (Local Event Flag Wait) 
state, 6-2 
Lexical functions, 3-15 
use in command procedure 
files, 3-15 
LIBSASN WTH MBX library 
routine, 5-9, 7-3 
Logical link, 2-4, 5-4 to 5-5, 
5-7, 5-11, 6-2 
aborting, 5-5, 7-8 
assigning channel for, 6-2, 
7-9 
completing connection of, 
5-8, 6-2, 7-5, 7-12 
disconnecting, 5-5, 5-ll, 
7-8, 7-15 
handshaking sequence, 5-7 
rejecting a request, 7-13 
requests, 2-5, 5-4, 5-7 to 
5-8, 6-2, 7-4 to 7-5, 
. 7-10 
SYSSNET, 5-8 
terminating, 5-5, 5-ll, 6-3, 
6-7, 7-9 ; 
Logical name, 2-1, 2-3, 2-9 
as device name, 2-9 
aS node name, 2-9 
DCL commands for, 3-4 
equivalence string, 2-9 
examples, 2-9 to 2-10 
in process logical name 
table, 2-9 
iterative translation, 2-10 
translation, 2-3, 2-9 
use of, 2-9 
use of underscore (_), 2-2, 
2-11 
Logical node name, 
See File specification 
LOGINOUT image, 2-5, 5-8, 7-6 
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Magnetic tape file 
restriction, 4-14 
MAIL object code, A-1 
Mailbox, 5-5, 7-2 to 7-3, D-1 
creating (S$CREMBX), 7-3 
message format, 7-3 
message types, D-l 
MERGE command, 3-13 
Message, 5-4 to 5-5, 5-10, 
6-5 to 6-6 
data, 5-10 
error, 3-19, C-l 
exchanging, 5-10, 6-3, 7-7 
interrupt, 5-4 to 5-5, 7-7 
mailbox, 5-5, 5-10, D-1 
network status, 5-5 
optional user data, 5-4 to 
5-5, 5-7, 7-1 
MIRROR object code, A-1l 
SMSGDEF macro, D-l 
Multiple inbound connects, 
5-4, 7-7, 7-17 


NAM (Name Block), B-7 

restrictions, 4-11 
NCB (Network Connect Block), 

5-7, 7-4 

destination descriptor, 7-5 
NET:, 7-2, 7-9 
Network command terminal, 1-6, 

2-11 

SET HOST command, 2-11 
Network example, 1-4 
Network name, 2-4 

declaring, 2-4, 7-6, 7-17 
Network task, 

declaring, 5-4, 5-9, 7-6 
Node name, 

See File specification 
Node-spec, 

See File specification 
Nonprivileged account, 2-7 
Nonprivileged network 

operations, 2-7 
Nonzero object, 

See Object 
Numbered object, 

See Nonzero object 


Object, 2-4, A-l 
examples, 2-5 
known, 2-4 
nonzero object, 2-4 
number, 7-6, 7-17 
task, 2-4 
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Object (Cont.) 
type, 2-4, 5-7, A-1l 
zero object, 2-4 
SOPEN call, 4-9, 4-12 
OPEN command, 3-17 
Optional user data, 
See Message 


SPARSE call, 4-12 
PHONE object code, A-1. 
PRINT/REMOTE command, 3-12 to 
3-13 
Privilege, 
associated with objects, 2-8 
Privileged, 
account, 2-7 
network operations, 2-7 
PURGE command, 3-10 


$QIO(IO$ ACCESS! IO$M_ ABORT) 
system service, 7-7 
format, 7-13 
SQIO(IO$ ACCESS) system 
service, 7-4, 7-7 
format, 7-10, 7-12 
$QIO(IO$_ACPCONTROL) system 
service, 7-7 
format, 7-17 
$QIO(IO$_DEACCESS!I0$M_ABORT) 
system service, 7-8 to 7-9 
format, 7-16 
$QIO(IO$_DEACCESS! IO$M_SYNCH) 
system service, 
format, 7-15 
SQIO(IO$ READVBLK) system 
service, 6-6, 7-14 
format, 6-6 
$QIO(IO$ _WRITEVBLK! 
IO$M_INTERRUPT) system 
service, 7-7 
format, 7-14 
$QIO(IOS_WRITEVBLK) system 
service, 6-5, 7-14 
format, 6-5 
Quotation marks, 3-5 
triple set of, 3-5 
Quoted string, 
See File specification 


RAB (Record Access Block), 
4-9, B-5 

READ command, 3-17 

REMACP object code, A-1l 
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Remote command terminal, 
See SET HOST and Network 
command terminal 
Remote file access, 1-1 
FORTRAN program example, 4-8 
MACRO programming interface, 
4-1, 4-8 
using DCL, 3-1 
uSing VAX-11 RMS, 4-1 
RMS control block field, B-1 
FAB, B-2 
NAM, B-7 
RAB, B-5 
XABALL, B-9 
XABDAT, B-10 
XABFHC, B-10 
XABKEY, B-11l 
XABPRO, B-12 
XABRDT, B~-13 
XABSUM, B-13 
RMS (Record Management 
Services), 1-2, 4-1 
calls for block I/0 
processing, 4-11 
calls for file processing, 
4-10 
calls for file specification 
processing, 4-11 
calls for record processing, 
4-10 
completion codes, 4-3 
control blocks, B-l 
file system characteristics, 
4-3 
MACRO programming examples, 
4-14 
programming notes, 4-8, 4-11 
restrictions on use of, 4-2, 
4-11 
service call summary, 4-9 
service calls, 4-1, 4-8 


SSEARCH call, 4-12 
SEARCH command, 3-13 
SET HOST command, 2-11 
SHOW LOGICAL command, 3-5 
SHOW TRANSLATION command, 3-5 
SORT command, 3-13 
Source task, 5-7 
SUBMIT/REMOTE command, 3-14 
Synchronous disconnect, 5-5, 
5-11, 7-8, 7-15 

SYSSNET, 5-8, 6-2, 7-6 

use in command procedures, 

3-18 “ 

SYSNAM privilege, 7-7 
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System service call, 1-2, 
5-11, 6-1, 7-1 
error messages, C-1l 
. Summary for nontransparent 
use, 7-1, 7-9 
summary for transparent use, 
6-1, 6-3 


Target task, 5-7 
Task, 1-2 
declaring. for network, 5-4 
object, 2-4 
source, 5-10 
specification examples, 2-5 
specification string, 2-1, 
2-4 
target, 5-10, 6-5 
taskname, 2-4 
Task-to-task communication, 
1-1, 2-1, 4-14, 5-1, 6-1, 
7-1 
nontransparent, 1-1, 5-l, 
5-4, 7-1 
nontransparent MACRO 
example, 7-18 
transparent, 1-1, 5-1, 6-1 
transparent FORTRAN example, 


5-2 
transparent MACRO example, 
6-8 
STRNLOG system service call, 
5-9 


TYPE command, 3-15 


UAF (User Authorization File), 
2-5, 5-8 
Underscore character (_), 2-2 
User Authorization File, 
See UAF 


VAX-11 RMS, 
see RMS (Record Management 
Services), 


Wild card character (*), 2-3 
WRITE command, 3-17 
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XABALL (Allocation Control XABRDT (Revision Date and Time 
XABDAT (Date and Time XAB), XABSUM (Summary XAB), B-13 
B-10 


‘XABFHC (File Header 
Characteristics XAB), B-10 


‘XABKEY (Key Definition XAB), Zero object, 
B-11 See Object 
XABPRO (File Protection XAB), 
B-12 
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